Use flatten translation keys

[lunny]

Crowdin does not remove empty lines in nested JSON translation files. Therefore, we use flattened translation keys instead. We have also updated the key-loading logic to ensure that empty values are not applied during translation.

[silverwind]

Or just flattify them as I had suggested? Would that avoid the problem?

[TheFox0x7]

Not sure what's the best approach here (flat/nested) and I don't know much about i18n so this is purely from code side.

[lunny]

Or just flattify them as I had suggested? Would that avoid the problem?

Based on Crowdin’s issue responses, yes—using a flat JSON structure would follow the skip_untranslated_strings: true configuration.

However, I’m not sure whether we should convert to a flat structure at this stage. It may be better to revisit this after the current change is merged and, if needed, propose a separate PR to handle the conversion.

[wxiaoguang]

However, I’m not sure whether we should convert to a flat structure at this stage. It may be better to revisit this after the current change is merged and, if needed, propose a separate PR to handle the conversion.

It is sure it should covert to a flat layout since #35489 (comment), when you first found that the translations were broken, it is a good chance to do all-in-one fix.

Since the translations are being hugely changed in recent days, I don't think it makes sense to do so again in the future.

You need a complete plan for this task, and ideally you should test the solution in a separate project & repo before applying it into Gitea's main repo.

[lunny]

However, I’m not sure whether we should convert to a flat structure at this stage. It may be better to revisit this after the current change is merged and, if needed, propose a separate PR to handle the conversion.

It is sure it should covert to a flat layout since #35489 (comment), when you first found that the translations were broken, it is a good chance to do all-in-one fix.

Since the translations are being hugely changed in recent days, I don't think it makes sense to do so again in the future.

You need a complete plan for this task, and ideally you should test the solution in a separate project & repo before applying it into Gitea's main repo.

Using a flat structure could be another PR, this PR will focus on fixing the current partial broken translations.

[silverwind]

Iterating over JSON as raw text feels wrong. I feel like this could also be done in a Node script that only works on the parsed content. In Javascript, map/object iteration is based on insertation order so parsing and stringifying JSON are strictly inverse operations to each other (unlike on golang where map iteration order is random).

[silverwind]

BTW why do we remove empty translations in first place? Couldn't we just make the translation code ignore empty translations and fall back to the default locale?

[wxiaoguang]

I also don't understand why so many fragile dirty patches, but not have a complete solution : #36225 (comment)

[lunny]

This is ready view again.

[wxiaoguang]

Why not keep the old logic? I believe old logic is stricter and better.

If the old logic didn't catch the empty strings, you won't even realize them.

[lunny]

I think there should be a tool to detect untranslated strings, but currently there isn’t one. (I will continue #34737 after this merged)

With the new logic, empty translations will simply be ignored. I also couldn’t find any mechanism in the old logic that helped surface these missing translations. Without such tooling, it’s impractical to manually discover empty translations, since you can’t reasonably check every page without knowing where the issue occurs.

[wxiaoguang]

Don't understand, it's up to you, you decide.

[tyroneyeh]

Hi Gitea team,

With the recent move from INI to JSON for translations, I’d like to suggest considering a further step: adopting a gettext-like i18n model where the English source string itself is used as the translation key.

For example:

with JSON like:

ctx.Tr("Sign In")

{
    "Sign In": "登录",
}

instead of symbolic keys such as:

ctx.Tr("sign_in")

{
    "sign_in": "登录",
}

The idea is to treat the English UI text as the single source of truth.

Benefits:

1. Readability and developer experience
   Using source strings directly makes code and templates much easier to read and review.
   Developers immediately see what will be rendered in the UI without having to look up keys.
   This lowers the barrier for new contributors and reduces cognitive overhead in reviews.

2. Less abstraction and maintenance overhead
   Symbolic keys introduce an extra layer that must be invented, documented, and kept in sync with the actual UI text.
   With source-string keys, the text itself is the identifier, which removes the need to design and maintain a separate key namespace.

3. Alignment with gettext ecosystem
   This model is widely used in gettext-based systems and many large projects.
   There is a mature ecosystem of tools for extracting strings, merging updates, and handling fuzzy matches when source text changes.

4. Strong fit with Crowdin’s workflow
   Crowdin’s translation UI is already source-text centric: translators work directly with the English source string and provide the target translation.
   Treating the source string as the key maps naturally to Crowdin’s translation units and avoids an extra indirection through symbolic keys.
   Crowdin also supports:

   • context display for translators,
   • deduplication of identical source strings,
   • and placeholder handling,
     which fits well with a gettext-like workflow.

5. Better experience for translators
   Translators see the real UI text as the primary identifier, rather than opaque keys like "repo.create" or "dashboard".
   This improves clarity and reduces the need for external documentation to explain what each key represents.

Maintainability considerations:

• Although changing a source string also changes the key, this is a well-known aspect of gettext-style systems and is addressed by existing tooling (fuzzy matching, merge tools, Crowdin’s similarity matching).
• For strings that need different translations in different contexts (e.g. "Open"), a context mechanism similar to gettext’s msgctxt could be introduced if needed.
• Overall, having a single, human-readable source of truth for UI text simplifies long-term maintenance compared to managing a parallel symbolic key space.

In summary, moving towards a source-string based i18n model could:

• improve code readability and contributor experience,
• reduce maintenance overhead around translation keys,
• and integrate more naturally with Crowdin and existing translation tooling.

I believe this direction would make Gitea’s i18n system cleaner and more approachable in the long run.

Thanks for your consideration.

[tyroneyeh]

There is a problem with including the URL directly in the translation.

[silverwind]

There should not be any HTML in translation, only text. There are ways with printf to avoid this but so far no one has gotten around to it.

[lunny]

There should be a next step to replace all these links but not in this PR.

[silverwind]

symbolic keys

I think it's okay to consider. Only downside that I see is the inability to "provide a hint" to the translator. Sometimes the same string can have different meanings based on context where it is used, and that context can be provided as part of the translation key.

[lunny]

symbolic keys

I think it's okay to consider. Only downside that I see is the inability to "provide a hint" to the translator. Sometimes the same string can have different meanings based on context where it is used, and that context can be provided as part of the translation key.

Yes, I think we need to have more time to consider this solution.