Translation Guidelines: Difference between revisions

From Thrive Developer Wiki
Jump to navigation Jump to search
No edit summary
(clarify the main repo document has info on adding translation keys)
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page has some guidelines for making translations for Thrive.
This page has some guidelines for making translations for Thrive.


You can translate Thrive on the [https://translate.revolutionarygamesstudio.com/ dedicated site]. More technical instructions for translating are in the [https://github.com/Revolutionary-Games/Thrive/blob/master/doc/working_with_translations.md main repo].
You can translate Thrive on the [https://translate.revolutionarygamesstudio.com/ dedicated site]. More technical instructions for translating are in the [https://github.com/Revolutionary-Games/Thrive/blob/master/doc/working_with_translations.md main repo] (includes info on adding new translation keys).


== No machine translations ==
== No machine translations ==


If you do not speak a language, do not translate it or vote on suggestions. Don't use machine translations (Google Translate etc.) unless you are familiar with the target language and can rewrite the translation to be correct and idiomatic in the target language.
If you do not speak a language, do not translate it or vote on suggestions. Don't use machine translations (Google Translate etc.) unless you are familiar with the target language and can rewrite the translation to be correct and idiomatic in the target language.
== Dictionaries / Glossaries ==
Weblate supports [https://docs.weblate.org/en/latest/user/glossary.html glossaries] for storing common terms in that occur in multiple pieces of text to translate. When translating a piece of text that uses word from the glossary, Weblate will automatically highlight these and show the translations for those words, this ensures that terms are consistently translated across different pieces of text. Thrive translation dictionaries are [https://translate.revolutionarygamesstudio.com/projects/thrive/glossary/ here].
Unfortunately this feature is pretty error prone to use, so here's a few things you should know:
* When creating new entries that are useful for multiple languages (marked as terminology) those ''must be'' first created for English, otherwise some funny things happen which you can't fix yourself.
* When creating a new entry the context and the English text should be set to be exactly the same. Also you need to usually uncheck the auto adjust the context when identical text already exists option, because otherwise Weblate won't complain about duplicate words and we end up with the same word being added 3 times. If the same word has multiple meanings only then can you make duplicate words like this, but each needs to have the explanation be different then to differentiate them. The explanation for a term can only be set ''after'' creating it.
* Put the key and the English text as the exact same text, after creating the dictionary entry you can then add the explanation text
* Only very few pieces of text should be marked as untranslatable because chemical process names and organelles do have different names in many languages
* When creating dictionary entries for multiple words strung together or short phrases, those most likely should be put in language specific dictionaries and '''not''' marked as terminology as that piece of phrasing is probably not a good unit to translate to other languages
* Avoid adding unnecessarily vague terms to the English dictionary. For example do not add the word "colony" as it may mean very different things later in the game, but instead add a word like "cell colony"
* When adding terminology start it with an upper case letter, for example "Microbe"
'''Adding English glossary entries requires extra permissions''' so if you do not have those, please ask someone else to create the entry. Do not create a language specific entry, add an explanation and make it into terminology, this will result in the language specific explanation being copied to the English one which you cannot modify. So the end result is bad info going into the English glossary.


== BBCode ==
== BBCode ==


Some text in the game use [https://en.wikipedia.org/wiki/BBCode BBCode] markup, these bbcodes are used to format texts (strings) into a more richer form. You can typically identify them with this syntax: <code>[tag]content[/tag]</code> in the strings. Normal bbcode tags like bold <code>[b]</code> etc. can have their content translated normally. In addition to the default bbcodes already supported by Godot, Thrive uses custom bbcodes that acts as an extension of the default ones (parsed into normal bbcodes internally) and are mainly used as helpers for Thrive-specific purposes. These custom bbcodes slightly differ from their default counterparts functionally and is marked with <code>thrive</code> namespace in the tag e.g. <code>['''thrive''':compound]</code>. As such it is important to keep in mind the correct way of handling these custom bbcodes while translating.
Some text in the game uses [https://en.wikipedia.org/wiki/BBCode BBCode] markup, these bbcode is used to format texts (strings) into more richer form. You can typically identify them with this syntax: <code>[tag]content[/tag]</code> in the strings. The tag ordering must not be changed, changing the tag order from right-to-left may result in the bbcode failing to render, like so: <code>[/tag]content[tag]</code>, as the bbcode parser always expect an opening tag to precede a closing tag (the one starting with slash) relative to the left-to-right writing system. So make sure to keep the tag order the same in any language.
 
Note that not all text in the game support bbcode. This means that you should ''not'' add bbcode to a translation where the original English text does not use bbcode. Also if you make suggestions that add bbcode somewhere these may be rejected on the grounds that the place where the text is used in the game does not support bbcode. Before these changes can be accepted a programmer needs to change Thrive to support bbcode in that place.
 
'''Normal bbcode tags like bold <code>[b]</code> etc. can have their content translated normally'''. In addition to the default bbcodes already supported by [https://en.wikipedia.org/wiki/Godot_(game_engine) Godot], Thrive uses custom bbcodes that act as an extension to the default ones (parsed into the default bbcodes internally) and are mainly used as helpers for Thrive-specific purposes. Functionally, these custom bbcodes slightly differs from their default counterpart and is marked with the <code>thrive</code> namespace in the tag e.g. <code>['''thrive''':compound]</code>. As such it is important to keep in mind the correct way of handling these custom bbcodes while translating.  


=== List of custom BBcode tags ===
=== List of custom BBcode tags ===
Line 17: Line 36:
==== Compound ====
==== Compound ====


Compound tag is used to display formatted name of a compound along with its associated icon, can be defined with the default form:
Compound tag is used to display formatted name of a compound along with its associated icon, can be declared with the default form:


<code>[thrive:compound type="<key>"][/thrive:compound]</code>
<code>[thrive:compound type="<key>"][/thrive:compound]</code>


Where the value (key) for <code>type</code> attribute is the compound's internal name. Notice that the content is empty, this is intended by default and it will be automatically filled with the default compound name based on the given <code>type</code> according to the current in-game locale. If for a specific language grammatical reasons you need to change this, a translation can be set by putting it as the content, for example: <code>[thrive:compound type="atp"]ATP:ksi[/thrive:compound]</code>, this will override the default compound name.
Where the value <key> for <code>type</code> attribute is the compound's internal JSON name. Notice that the content is empty, this is intended by default and it will be automatically filled with the default compound name based on the given <code>type</code> according to the current selected in-game locale. Default compound name here refers to the default translation of a compound, for example "Hydrogen Sulfide" translates to "Rikkivety" in Finnish, this will be the output of the bbcode. If for a specific language grammatical reasons you need to change this to make a sentence more sensible, a special translation can be set by inserting it as the content, for example: <code>[thrive:compound type="atp"]ATP:ksi[/thrive:compound]</code> will override the translation to "ATP:ksi" as the output.
 
'''Note:''' Currently a fallback syntax is supported by having the tag as <code>[thrive:compound]<key>[/thrive:compound]</code>. This is obsolete and may be removed in the near future.


==== Input ====
==== Input ====


Input tag is used to display a key prompt image of the primary input event for an action (like "G" for engulfing), can be defined simply with:
Input tag is used to display a key prompt image of the primary input event for an action (like "G" for engulfing), can be declared simply with:


<code>[thrive:input]<key>[/thrive:input]</code>
<code>[thrive:input]<key>[/thrive:input]</code>


The key to be inserted in the content is the internal name of an action assigned in the input map.
The <key> to be inserted into the content is the internal name of the action assigned in Godot's [https://docs.godotengine.org/en/stable/classes/class_inputmap.html input map].


Typical usage form:
Typical usage form:


<code>[thrive:input]g_toggle_engulfing[/thrive:input]</code>.
<code>[thrive:input]g_toggle_engulfing[/thrive:input]</code>.
==== Constant ====
Constant tag is used to display values from the source code. It uses a compiled list of keys to retrieve the values.
<code>[thrive:constant]OXYTOXY_DAMAGE[/thrive:constant]</code>.
The keys can also use attributes which can be different for every key.
<code>[thrive:constant format=F5]OXYTOXY_DAMAGE[/thrive:constant]</code>
For a complete list of constants and their attributes take a look at the [https://github.com/Revolutionary-Games/Thrive/blob/master/src/gui_common/CustomRichTextLabel.cs source code]
==== Resource ====
Very similar to the compound tag. For example: <code>[thrive:resource type="rock"][/thrive:resource]</code>
This tag also supports overriding the used name for the resource. Also note that the resource bbcode by default does not show the name, only an icon.
==== Icon ====
This tag inserts an icon into the text. The tag content is the technical name of the icon and may not be translated. Leave any tags like <code>[thrive:icon]ConditionFulfilled[/thrive:icon]</code> as they are when translating.
== C# formatting ==
Thrive uses the C# programming language and as such we use the string formatting functionality it has. Many of the translated pieces of text have placeholders like <code>{0}</code>, <code>{1}</code>, <code>{2}</code> and so on. These can be used to reorder parts of the text that are inserted into the middle of the translated strings. For example some languages may need to change the order of words near a species name to make the text sound natural. Reordering the placeholders supports this.
The placeholders can have additional formatting specified in them, for example <code>{0:#,#}</code> (the special formatting rule is separated from the placeholder's number with a ":"). These should in most cases be left as is. Even if it seems like there is a part that specifies language specific formatting (the comma in the previous example). In the case of Finnish <code>{0:#,#}</code> actually correctly replaces the comma with spaces when formatting, for example resulting in "100 000 000". This means that in most cases the placeholders, including the special formatting instructions in them, should be left as-is, but they can be reordered to make sentence structure work better in the translation.


== Reconstructing made-up words ==
== Reconstructing made-up words ==
Line 60: Line 105:


Due to the way Godot passes us the name, some key names are pretty simple like "HOME", but might conflict with other translations. If such cases are found we'll handle this by differentiating the key and the other word translation.
Due to the way Godot passes us the name, some key names are pretty simple like "HOME", but might conflict with other translations. If such cases are found we'll handle this by differentiating the key and the other word translation.
== Formal vs. Informal Language ==
Some languages have formal and informal forms (or styles). For these the following advice should be followed: whichever is already used in other translations near the text should be used (this only applies when a translation has not been started).
For deciding if formal or everyday language should be used, pick whichever is more commonly used in games and is less likely to cause people to wonder why it was picked for Thrive overall. The tone of Thrive overall is not very joke-y, but not also dead serious either.
== Store pages ==
Thrive store page content is also up on Weblate to be translatable. These translations will only be used once checked by trustworthy individuals who can commit time to checking and translating the text over a longer period of time (so that store pages in other languages won't get outdated).
At the time of writing no one has taken on the task of reviewing and using the translations. See for more info: https://forum.revolutionarygamesstudio.com/t/community-translations-for-store-content/833


== Merging from Weblate ==
== Merging from Weblate ==


This is a note for developers: translation commits need to be merged normally otherwise weblate will not be happy and will keep complaining about conflicts.
This is a note for developers: translation commits need to be merged normally otherwise weblate will not be happy and will keep complaining about conflicts.

Latest revision as of 09:17, 22 April 2023

This page has some guidelines for making translations for Thrive.

You can translate Thrive on the dedicated site. More technical instructions for translating are in the main repo (includes info on adding new translation keys).

No machine translations

If you do not speak a language, do not translate it or vote on suggestions. Don't use machine translations (Google Translate etc.) unless you are familiar with the target language and can rewrite the translation to be correct and idiomatic in the target language.

Dictionaries / Glossaries

Weblate supports glossaries for storing common terms in that occur in multiple pieces of text to translate. When translating a piece of text that uses word from the glossary, Weblate will automatically highlight these and show the translations for those words, this ensures that terms are consistently translated across different pieces of text. Thrive translation dictionaries are here.

Unfortunately this feature is pretty error prone to use, so here's a few things you should know:

  • When creating new entries that are useful for multiple languages (marked as terminology) those must be first created for English, otherwise some funny things happen which you can't fix yourself.
  • When creating a new entry the context and the English text should be set to be exactly the same. Also you need to usually uncheck the auto adjust the context when identical text already exists option, because otherwise Weblate won't complain about duplicate words and we end up with the same word being added 3 times. If the same word has multiple meanings only then can you make duplicate words like this, but each needs to have the explanation be different then to differentiate them. The explanation for a term can only be set after creating it.
  • Put the key and the English text as the exact same text, after creating the dictionary entry you can then add the explanation text
  • Only very few pieces of text should be marked as untranslatable because chemical process names and organelles do have different names in many languages
  • When creating dictionary entries for multiple words strung together or short phrases, those most likely should be put in language specific dictionaries and not marked as terminology as that piece of phrasing is probably not a good unit to translate to other languages
  • Avoid adding unnecessarily vague terms to the English dictionary. For example do not add the word "colony" as it may mean very different things later in the game, but instead add a word like "cell colony"
  • When adding terminology start it with an upper case letter, for example "Microbe"

Adding English glossary entries requires extra permissions so if you do not have those, please ask someone else to create the entry. Do not create a language specific entry, add an explanation and make it into terminology, this will result in the language specific explanation being copied to the English one which you cannot modify. So the end result is bad info going into the English glossary.

BBCode

Some text in the game uses BBCode markup, these bbcode is used to format texts (strings) into more richer form. You can typically identify them with this syntax: [tag]content[/tag] in the strings. The tag ordering must not be changed, changing the tag order from right-to-left may result in the bbcode failing to render, like so: [/tag]content[tag], as the bbcode parser always expect an opening tag to precede a closing tag (the one starting with slash) relative to the left-to-right writing system. So make sure to keep the tag order the same in any language.

Note that not all text in the game support bbcode. This means that you should not add bbcode to a translation where the original English text does not use bbcode. Also if you make suggestions that add bbcode somewhere these may be rejected on the grounds that the place where the text is used in the game does not support bbcode. Before these changes can be accepted a programmer needs to change Thrive to support bbcode in that place.

Normal bbcode tags like bold [b] etc. can have their content translated normally. In addition to the default bbcodes already supported by Godot, Thrive uses custom bbcodes that act as an extension to the default ones (parsed into the default bbcodes internally) and are mainly used as helpers for Thrive-specific purposes. Functionally, these custom bbcodes slightly differs from their default counterpart and is marked with the thrive namespace in the tag e.g. [thrive:compound]. As such it is important to keep in mind the correct way of handling these custom bbcodes while translating.

List of custom BBcode tags

Note: Thrive BBCode tags use keys (not to be confused with input keys; marked as <key> in the descriptions below) to look up information from the game configuration json and keys must not be translated. The tags (text inside brackets [...]) in general should be left as-is in any translations, the content however may be translated whenever possible.

Compound

Compound tag is used to display formatted name of a compound along with its associated icon, can be declared with the default form:

[thrive:compound type="<key>"][/thrive:compound]

Where the value <key> for type attribute is the compound's internal JSON name. Notice that the content is empty, this is intended by default and it will be automatically filled with the default compound name based on the given type according to the current selected in-game locale. Default compound name here refers to the default translation of a compound, for example "Hydrogen Sulfide" translates to "Rikkivety" in Finnish, this will be the output of the bbcode. If for a specific language grammatical reasons you need to change this to make a sentence more sensible, a special translation can be set by inserting it as the content, for example: [thrive:compound type="atp"]ATP:ksi[/thrive:compound] will override the translation to "ATP:ksi" as the output.

Input

Input tag is used to display a key prompt image of the primary input event for an action (like "G" for engulfing), can be declared simply with:

[thrive:input]<key>[/thrive:input]

The <key> to be inserted into the content is the internal name of the action assigned in Godot's input map.

Typical usage form:

[thrive:input]g_toggle_engulfing[/thrive:input].

Constant

Constant tag is used to display values from the source code. It uses a compiled list of keys to retrieve the values.

[thrive:constant]OXYTOXY_DAMAGE[/thrive:constant].

The keys can also use attributes which can be different for every key.

[thrive:constant format=F5]OXYTOXY_DAMAGE[/thrive:constant]

For a complete list of constants and their attributes take a look at the source code

Resource

Very similar to the compound tag. For example: [thrive:resource type="rock"][/thrive:resource]

This tag also supports overriding the used name for the resource. Also note that the resource bbcode by default does not show the name, only an icon.

Icon

This tag inserts an icon into the text. The tag content is the technical name of the icon and may not be translated. Leave any tags like [thrive:icon]ConditionFulfilled[/thrive:icon] as they are when translating.

C# formatting

Thrive uses the C# programming language and as such we use the string formatting functionality it has. Many of the translated pieces of text have placeholders like {0}, {1}, {2} and so on. These can be used to reorder parts of the text that are inserted into the middle of the translated strings. For example some languages may need to change the order of words near a species name to make the text sound natural. Reordering the placeholders supports this.

The placeholders can have additional formatting specified in them, for example {0:#,#} (the special formatting rule is separated from the placeholder's number with a ":"). These should in most cases be left as is. Even if it seems like there is a part that specifies language specific formatting (the comma in the previous example). In the case of Finnish {0:#,#} actually correctly replaces the comma with spaces when formatting, for example resulting in "100 000 000". This means that in most cases the placeholders, including the special formatting instructions in them, should be left as-is, but they can be reordered to make sentence structure work better in the translation.

Reconstructing made-up words

Many words used in Thrive aren't real words. Instead they have been constructed specifically for use in Thrive. These should be attempted to be translated in the same way they are formed for English.

For example the word "Chemoplast" is made up of the parts "chemo" and "plast", which can be separately translated. For example a possible Finnish translation would be "kemo" and "plasti" to form "kemoplasti". This way translations can be done to reconstruct what the word could look like if Thrive was developed in the target language. Some terms can be left as-is if no good reconstruction can be done.

What should also be kept in mind is the pattern that organelles follow in the target language. The reconstructed organelle names should be made to conform to the patterns that real organelle names follow in the target language. This will also apply to words made up for later stages.

Some more examples were mentioned on the forums.

No broken translation

Please don't submit broken translations (other than as suggestions) on the translation site as if those end up in the game (someone doesn't remove it), then the game might be unplayable in the language you are translating. It is always better to let the default English text be used rather than an inadequate translation.

Dismissing checks

Some of the automated checks on the translation website can be false positives. As such they can be dismissed if the translation is correct and styling is good for the target language.

Key name translations

If you look to the right-hand side there is an info panel about each piece of text. If the source location contains "key_mapping/KeyNames.cs" then it means that, that translation is for a key name. Keys should be translated as a commonly accepted name for them in the translated language. If there isn't one used then whatever is usually printed in keyboards in that country should be used, this often seems to match what the English name for the key is.

Due to the way Godot passes us the name, some key names are pretty simple like "HOME", but might conflict with other translations. If such cases are found we'll handle this by differentiating the key and the other word translation.

Formal vs. Informal Language

Some languages have formal and informal forms (or styles). For these the following advice should be followed: whichever is already used in other translations near the text should be used (this only applies when a translation has not been started).

For deciding if formal or everyday language should be used, pick whichever is more commonly used in games and is less likely to cause people to wonder why it was picked for Thrive overall. The tone of Thrive overall is not very joke-y, but not also dead serious either.

Store pages

Thrive store page content is also up on Weblate to be translatable. These translations will only be used once checked by trustworthy individuals who can commit time to checking and translating the text over a longer period of time (so that store pages in other languages won't get outdated).

At the time of writing no one has taken on the task of reviewing and using the translations. See for more info: https://forum.revolutionarygamesstudio.com/t/community-translations-for-store-content/833

Merging from Weblate

This is a note for developers: translation commits need to be merged normally otherwise weblate will not be happy and will keep complaining about conflicts.