SUG 9.2: inconsistencies with index.json common_name(s) field

I have been reading through the SUG to understand the structure of sky culture data, especially the common_name/common_names field. I have noticed some inconsistencies that I think should be addressed:

SUG 9.2.4: Constellation -> common_name

missing field translators_comments (9.2.7 has it), generate-pot.py uses it
index.json (ex. arabic_arabian_peninsula) uses references but this is neither documented nor read by Constellations.cpp
Constellations.cpp and generate-pot.py use context but this is not documented

SUG 9.2.5: Asterisms -> common_name

missing field translators_comments (9.2.7 has it), generate-pot.py uses it
Bug: SUG mentions references in common_name, but Asterisms.cpp tries to read data["references"] instead of data["common_name"]["references"] (GZ EDIT: fixed)
unlike Constellations, Asterisms.cpp does not use context, but generate-pot.py does, but the field is not documented in the SUG

SUG 9.2.7: Sky Culture -> common_names (Names of Stars, Planets and Nonstellar Objects)

SUG says translator_comments, index.jsons use translators_comments (with an extra "s")
the function process_names in generate-pot.py uses context in common_names, but this is not documented in the SUG

These are just examples of what I have found so far. I will edit this issue if I find more.
I suppose a solution would be to introduce a single section in the SUG that defines the structure of common_name/common_names, including all the fields and thus serving as a "single source of truth" so its easier to update and maintain.

@10110111

Thanks, some of these pesky details are probably still not complete.

The translator(s)_comments are not used in the program, but should help adding additional context for translators working on Transifex without necessarily seeing the place in the program where it's used. But agreed, should be translators_comments everywhere, and is optional.

On "Context", I cannot even say, @10110111 , @alex-w do we need to fill context everywhere in index.json, or could generate-pot.py add context entries (just the SC name?)? (And how many do exist now and are used - does a change mean retransifexing what feels like ~8000 name entries yet once more?)

On references vs common_name/references: For Asterisms and star names, I have implemented a "reference exclusion" so that if you don't like the asterisms or also star names from ref."X", those entries which only have "X" in their reference list are not used. (e.g. this internal ~1970 NASA memorandum which brings star name duplicates with Roman numerals. IMO nobody outside NASA/JPL has ever used them, so I don't like to see them usually. Same goes for tertiary textbooks that just brought misprinted names.)

The structure of the "common_name" dict inside Constellation and Asterism should probably be identical, and an L2 section "Asterisms" added to description.md. The skyculture/common_names section is IMO different by design, buy yes, the role of "context" is not really documented and may still have inconsistencies.

Thank you for suggesting documentation improvement.

Context maybe really helpful for star names, because same English name may have different translation in some languages (we have a few bug reports for this case)

My next issue is that I don't know whether I should really rewrite the section of the SUG or not. On one hand I think consistency is important and it will only get worse with each update. On the other hand, the "common_name" attribute seems like such a small and rather low priority topic that I do not want to waste your time and make big changes to the SUG.

A few answers or EDITS: solutions from June 13 (-[X]-):

#	Location	Issue
1	Asterism.cpp	byname is not read from common_name; parity with Constellation.cpp needed.
re	-[X]-	So far 'byname' was needed for constellations only. Do we need to implement something which will not be used?
2	Asterism.cpp	context is not read from common_name; parity with Constellation.cpp needed.
re	-[X]-	fixed.
3	Asterism.cpp	references is read from data["references"] (top-level asterism object) instead of data["common_name"]["references"]. Bug or intentional design? Needs clarification and consistent placement in schema.
re	-[X]-	fixed.
4	Constellation.cpp	references inside common_name is recognized in existing index.json files but is not read by the C++ code. Needs either code support or removal from data files.
re	-[X]-	Of the two options, option three applies. References per-constellation, per-asterism, per-star or per-dso need not be used in code. They are however important to know in data file where we got our wisdom from. Never remove a reference entry please! If there is demand, display on screen is still a future option.
5	StarMgr.cpp	context is not read; star name translations cannot be disambiguated at runtime even though generate-pot.py uses it for .pot generation.
re	-[ ]-	This should be fixed indeed.
6	SolarSystem.cpp	byname and references are not read for planet names.
re	-[X]-	Same: byname never used by now, references important for scientific rigor but not displayed.
7	NebulaMgr.cpp	byname and references (per-name) are not read for DSO names in the new index.json path (TODO comment in code).
re	-[X]-	Same: byname never used by now, references important for scientific rigor but not displayed. Not sure if we want to clutter screen by extracting and displaying source for each DSO name. I have implemented a reference exclusion option ("don't display those overly fancy names from this or that reference") which actually reads and processes the references. So far this is a manual tweak, time permitting would allow adding yet another menu panel.
8	generate-pot.py	transliteration and IPA are not extracted into .pot files. Intentional (not translated)? Should be clarified in docs.
re	-[X]-	Intentional. Indeed, never translated, no need in .pot.
9	SUG §9.2.7	Documents translator_comments (no trailing s); all index.json files and generate-pot.py use translators_comments. The correct canonical name needs to be chosen and applied uniformly.
re	-[X]-	fixed.
10	SUG §9.2.4 (CON)	context and translators_comments are missing from the documented field list.
re	-[X]-	fixed.
11	SUG §9.2.5 (AST)	context and translators_comments are missing from the documented field list.
re	-[X]-	fixed.
12	SUG §9.2.7 (STAR/PLN/DSO)	context is missing from the documented field list.
re	-[X]-	fixed.
13	StarMgr.cpp	byname is read and translated in loadCultureSpecificNameForStar (the HIP … / Gaia DR3 … path) but is silently ignored in loadCultureSpecificNameForNamedObject (the NAME … path), where both byname and bynameI18n are left empty. Stars resolved by common name therefore lose their byname at runtime.
re	-[X]-	The byname feature was introduced for yet another name or explanatory add-on displayed for constellations, so leaving it empty in asterisms, stars, DSO, planets, etc. is not a practical problem. Of course, the availability of bynames in all possible elements could invite some SC author to attempt making used of it. Does anybody feel a need for it? Else we can just also document that this is available for CON only. --> Let's allow it for stars.
14	generate-pot.py / loaders	english is enforced inconsistently: generate-pot.py emits a warning for CON and AST if absent, but silently skips STAR/PLN/DSO entries. Uniform enforcement (e.g. always warn) needed.
re	-[X]-	Agreed, warnings should be added. EDIT As of June 13. there is a warning (L.407).

Maybe it's not so important that You rewrite the SUG chapter. However, this discussion is important to identify unclarities/inconsistencies and finalize the description which was growing for two years now, e.g., I have my own knowledge voids in the whole translation business around the proper use of the context entry, see above. And at some point, we wanted to have one common JSON format for this project, S-web and S-mobile even if not all programs use all features, so that SCs can be shared among installations, e.g. developed on desktop, and added on mobile or so. A complete format description would surely be helpful.

So far 'byname' was needed for constellations only. Do we need to implement something which will not be used?

No, thats fine. I'll update the table above so that asterisms dont have a byname.

Must have a closer look into what you mean.

Asterism.cpp line 107: QVariantList refsVariants=data["references"].toArray().toVariantList();
All other values of the name are read like this:

const QJsonValue names = data["common_name"];
if (names.isObject())
{
	culturalName.translated = names["english"].toString().trimmed();
	culturalName.native = names["native"].toString().trimmed();
	culturalName.pronounce = names["pronounce"].toString().trimmed();
	culturalName.IPA = names["IPA"].toString().trimmed();
	culturalName.transliteration = names["transliteration"].toString().trimmed();
}

The code tries to read references inside "asterisms": [] in the json. But if we look at sky cultures like arabic_indigenous, the references field is inside common_name. I hope this makes sense.

Is a context entry used anywhere?

Probably not a full answer but some interesting things I found:

ConstellationMgr.cpp uses the context field of constellations in the updateI18n function.
Its used for translatedI18n, pronounceI18n and bynameI18n context.

SolarSystem.cpp line 638-639 use the context for i18n translated and pronounce for planets

cName.translatedI18n=trans.qtranslate(cName.translated, json["context"].toString());
cName.pronounceI18n=trans.qtranslate(cName.pronounce, json["context"].toString());

NebulaMgr.cpp lines 2008 and 2011 use it for DSO(?) translated i18n and pronounce i18n context

cName.pronounceI18n   = trans.qtranslate(json["pronounce"].toString(), json["context"].toString());
cName.translatedI18n  = trans.qtranslate(json["english"].toString(), json["context"].toString());

The StarMgr.cpp and Asterism.cpp do not read or set the context at all (issue 2 and 5)

For example in StarMgr.cpp the context could be inserted here:

cName.pronounceI18n=trans.qTranslateStar(cName.pronounce);
cName.translatedI18n=trans.qTranslateStar(cName.translated);
cName.bynameI18n=trans.qTranslateStar(cName.byname);

The asterism class never sets any i18n values.

Fix asterism reference exclusion (see #4891)

A few clarifications in skyculture names (see #4891)

@alex-w

From the list above, I think only point 5, star name context for disambiguation in StarMgr::updateI18n(), is open. But as I see it, with StarMgr::culturalNamesMap, context may have to be included in the CulturalName struct. @alex-w , @10110111 ?

Adding support the context into qTranslateStar() method (the context string may be empty) and storing the context into CulturalName struct of course (to use for qTranslateStar). But this task must be postponed to 26.3.

Probably this task should be postponed to 26.4.

OK, 26.4. But let's solve Asterism issues also then.

Navigation Menu

Repository navigation

SUG 9.2: inconsistencies with index.json common_name(s) field #4891

SUG 9.2.4: Constellation -> common_name

SUG 9.2.5: Asterisms -> common_name

SUG 9.2.7: Sky Culture -> common_names (Names of Stars, Planets and Nonstellar Objects)

6 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

SUG 9.2: inconsistencies with index.json common_name(s) field #4891

Description

SUG 9.2.4: Constellation -> common_name

SUG 9.2.5: Asterisms -> common_name

SUG 9.2.7: Sky Culture -> common_names (Names of Stars, Planets and Nonstellar Objects)

Activity

gzotti commented on Apr 29, 2026

github-actions commented on Apr 29, 2026

alex-w commented on Apr 29, 2026

6 remaining items

xLPMG commented on May 1, 2026

gzotti commented on May 1, 2026

gzotti commented on May 1, 2026

xLPMG commented on May 1, 2026

gzotti commented on Jun 13, 2026

alex-w commented on Jun 19, 2026

alex-w commented on Sep 7, 2026

gzotti commented on Sep 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions