docs/Translating/Translating.md
The translation files are at /android/assets/jsons/translations
If you're adding a new language, see Adding a new language.
If you're adding stuff to an existing language, simply start editing the file!
You don't need to download anything, all translation work can be done on the Github website :)
When you feel that you're ready to add your translation to the game, you'll need to create a merge request, which takes your changes and puts them into the main version of the game - it's pretty straightforward once you do it
Please note that Right-to-Left languages such as Arabic and Hebrew are not supported by the framework :/
There are two special entries that won't show in the game but are automatically used to provide short and long descriptions for F-Droid (and possibly other stores soon). They're near the beginning of each language file and marked "Fastlane". See the comments just above each for help, and where to find the actual english original to translate. Do not overlook the note on line breaks in Other notes for the full description!
=") contains square brackets, you will have to include each of them verbatim in your translation, but you can move them. Upper/lower case is relevant! e.g. All [personFilter] are cool can be translated as Tous les [personFilter] sont cool, but not as Tous les [personnages] sont cool, and neither as Nous sommes vraiment cool. Failing this is the main cause of your PR's showing up with red "x"es and "checks failed".Like most open-source projects, Unciv is developed at Github, so if you don't have a user you'll first have to create one. The way Github works is the following:
When you ask to 'edit' a file in yairm210/Unciv, these stages happen automatically - but it's important to understand what's happening behind the scenes do you understand where the changes actually are!
Unciv automatically runs unit tests on every PR or push adding commits (inless you're new, in which case someone needs to start the workflows). These contain checks for the rules already described here - a failure means either you didn't follow all the rules (see Pitfalls), or problems outside your control.
To see what went wrong, open your PR, look for the "failing check" entry under "Some checks were not successful", and click the "..." menu and "View details" (or look for the red "x" near a commit ID and click that). Scroll a little ways up and look for an entry similar to ' TranslationTests > allTranslationsHaveCorrectPlaceholders FAILED' - the exact explanation is in the lines above and below.
Read and fix all reported errors and commit the fixes. Wait for the checks to re-run, rinse, repeat. You'll learn what it takes to avoid such pitfalls quickly.
Each untranslated phrase will have a ` # Requires translation!" line before it, so you can quickly find them. You don't need to remove them yourself - they will be automatically removed the next time we rebuild the file.
Do as much as you're comfortable with - it's a big game with a lot of named objects, so don't feel pressured into doing everything =)
If you're making changes to your own repo, make sure that you make the branch you're changing is based on Unciv's master branch
Some entries have line breaks expressed as \n: Your translation can and in most cases should use them as well, but you do not need to distribute them exactly as in the original. Try to find a translation that reads nicely, then place the line break codes at roughly the same intervals as the original uses (less if your language's glyphs are wider than latin ones). Important: You cannot use normal line breaks, you must use the \n codes, normal line breaks are not part of a translation.
Chinese tutorial: 如果你是中国人，那么恭喜你运气不错！这里有Unciv中文开发者们专门为中文翻译工作者准备的（十分详尽）教程视频。：(Video On Bilibili)
If any of the following steps are beyond your skillset, ask for help. All but the first two steps can be postponed.
= corresponds exactly with your new language file name, case-sensitive, without extension.When displaying text, the underlying libraries (libGdx and possibly lwjgl3/GWT) that Unciv uses assume one codepoint in the UTF-16 representation corresponds to one rendered glyph, which causes incorrect display of languages making heavy use of diacritics or of characters outside the basic multilinguial plane like most emoji. A language file can activate a "trick", where combinations of codepoints that should render as one single glyph are mapped into a "fake alphabet", which is created on the fly in the Private Use Area defined by Unicode.
To activate this feature, set diacritics_support = true in your translation. There are a few additional "settings" - translation lines where the "translation" is some control instruction instead.
All of these are optional, though your language may show glitches unless you define some. For example, Bangla needs a definition for U+09CD, where the Unicode category does not fully define the required behaviour.
Each of the following definitions represents zero or more characters, and can simply list them as one string. For readability, they can also be quoted (" surrounding the entire definition), characters can be separated by spaces, or you can use standard "U+xxxx" representations (these need space separators). These entries, unlike the rest of a translation file, also support entry-specific comments: After the code(s), from a '#' to the end of the line. Search for the information about the Unicode support in your language, e.g. on https://www.unicode.org/charts/ for information on which codes you might need to specify. If your language does not need these, feel free to ignore, or use "" to avoid the "requires translation" mark.
diacritics_support: This entry must be set to "true" for the diacritics support to work at all. Any other value will cause text to be passed through unchanged.unicode_block_start_character and unicode_block_end_character: These define the range of characters that should be considered. One character or code each. Defaults to the entire BMP range.
All characters in this range will be categorized, those undefined by Unicode, controls or punctuation, or those outside the range will pass through and reset the diacritics engine for the rest of the line, that is, pending potential combinations will be flushed.
Limiting this range - e.g. to the Unicode page dedicated to your language - is a performance optimization, but ultimately not required.left_joining_diacritics: Optionally define additional codes meant to join with the character to the left of them, by default the unicode categories "Mn" and "Mc" within the range described above are used.right_joining_diacritics: Optionally define additional codes meant to join with the character to the right of them, by default none.left_and_right_joiners: Optionally define additional codes meant to join with the character to the left AND with the character to the right, by default noneThese are processed in listed order and can override previous categorizations per character codepoint.
Thus a code specified in left_and_right_joiners can be in the "Mn" unicode category, which would put it into the left_joining_diacritics, but will still work, because the later definition overrides the earlier one.