New XML-based localisation format (DRAFT)

[originalfoo]

@VictorPhilipp If you can dump some basic info in here - even just links to existing C# or xml files or whatever, if it's obvious from looking at them what to do - I'll add a wiki page to document it.

[krzychu124]

I've made quick test.
It's quite easy and seems to be working (at least in the mod options):

• put new translation file in `TLM/TLM/Resources',
• set Build Action to Embedded Resource in file Properties (Visual Studio),
• add following lines into static constructor of class below:
  • AVAILABLE_LANGUAGE_CODES.Add("suffix_of_new_language");
  • LANGUAGE_LABELS["suffix_of_new_language"] = "lang name in native language"; - label displayed as language option the mod options"

suffix_of_new_language has to be the same as suffix of language file in Resources
e.g. lang_en.txt, so suffix en obviously 😉

https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/blob/a6f24080ec10186136c89e9b93682c51f42d7896/TLM/TLM/UI/Translation.cs#L23-L53

[originalfoo]

There isn't a lang_en.txt in the resources folder though?

[originalfoo]

I'm not sure what this step means:

• set Build Action to Embedded Resource in file Properties (Visual Studio),

I would assume one just goes to the Resources folder, right-click to add new item, and then select the lang file?

And then edit the Translation.cs in the usual manner?

[originalfoo]

Ah, after adding file to Resources folder in VS, right-click file > properties, then set Embedded Resource:

[originalfoo]

Also, what are we doing about lang_template.txt?

Currently our updated localisation guide states to use lang.txt as that contains the actual text of the locale keys.

[originalfoo]

Here's initial draft in the wiki: https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/wiki/Adding-a-new-language

[VictorPhilipp]

Oh, you're too quick for me :)

lang_template.txt is there to help translators such that they don't have to remove every English translation from the lang.txt when they introduce a new language.

(off topic) What do you think about moving to XML-based localization files? For example:

• 👍 Everything would be in one file, no need to add new resources
• 👍 Translators see all available translations for each key at once which could be helpful
• 👎 Missing translations might be hard to find - tools needed

[krzychu124]

I like idea of moving to XML. Then we could automate the process of registering new language.

[originalfoo]

We could include a section in the xml for the locales and their captions too:

...
<Languages>
   <Language lang="en">English</Language>
   <Language lang="fr">Français</Language>
   ...
</Languages>
<Translations>
    <Translation key="Road_type">
        <Value lang="en">Road type</Value>
        <Value lang="fr">Type de route</Value>
        ...
    </Translation>
    ...
</Translations>
...

Would we still use \n for newlines, or would we start using <![CDATA[ ... ]]> stuff?

Also, I think we have to factor in translators too - is using XML making their job more complex or easier? If the current format is easier for them, maybe we could have some sort of build process that converts the lang_*.txt in to centralised lang.xml file?

What happens if two users submit translations at the same time (which happened recently - French and Japanese if memory serves)? I assume github will be able to merge easily, but will any merge-related stuff on-screen deter translators?

Another consideration is RAM consumption - would we be loading and retain whole XML, or would we just parse it to get the relevant strings for the active language?

[originalfoo]

Regarding missing translations, we could spit those out to the log file in DEBUG builds.

• Get list of languages from the translation xml
• For each <Translation>
  • For each <Language>
    • If <Value> not found for the language, trace details to log file

Better still, if we could dump the info in to a markdown file we could then add that to the repo or wiki so translators know what needs translating in their language. We could also state what percentage each language is at.

If a specific <Translation> isn't yet localised to a specific language, the <Value> for that language would be omitted from the file. In RELEASE builds, when loading the local file, we'd just default to the <Value lang="en"> for the given <Translation> if the desired language is not found.