| 1 | | = Requirements = |
| 2 | | |
| 3 | | == i18n system == |
| 4 | | The language editing tool provides an interface to this system. |
| 5 | | |
| 6 | | The i18n design is mostly explained in [http://www.wildfiregames.com/forum/index.php?showtopic=1331 this thread]. ''(In that thread, it seems like I was unaware of 'ngettext' for handling plurals in gettext; but ngettext is not a particularly nice solution anyway, since you have to duplicate the English phrase in the code, and since it can't handle multiple number variables in a single phrase (like "$f file(s) in $d director(y|ies)").)'' |
| 7 | | |
| 8 | | It is meant to be simple for most of the game developers (e.g. nobody has to care about languages when they're designing scenarios), and flexible enough to support natural-sounding phrases in any language. |
| 9 | | |
| 10 | | Most of the effort into the game's presentation is spent on graphics, and much of the rest on sound. It would seem reasonable to spend a fair amount on the text, so that the game is nice to read, rather than just using text to present data in the simplest (least fancy, and least interesting) way. Or maybe nobody else cares, and that's just me... |
| 11 | | |
| 12 | | I think the system is entirely implemented, except for actually editing the list of translations in a friendly way. However, since the game currently doesn't make much use of the i18n system, it should be easy to make changes to the way it works (if such changes are necessary/useful). |
| 13 | | |
| 14 | | |
| 15 | | == Data == |
| 16 | | |
| 17 | | There are three main sets of data per language: |
| 18 | | * '''Phrases''' - a set of key=>value pairs, where the key is the English identifier for the phrase, and the value is the translated version. (In some cases, this could be a long piece of text (for in-game help, historical background, etc). I'm not sure how best to handle this.) |
| 19 | | * '''Nouns''' - mainly corresponding to entity names. Units are almost always named in their native language (e.g. "Neyzedar Madi" for Persian spearmen), so it is not necessary to translate them into other languages; but some other entities ("cow", "tree", "grass", etc) do need translations. Nouns are never used directly in the game - they are inserted into phrases, like "Selected $unit". |
| 20 | | ''(I'm not certain about the next bit.)'' To get decent grammar, the game needs to be able to say "Selected a cow", "Selected an oak tree", "Selected grass". In most cases, it can guess whether to use 'a' or 'an' based on the first letter, but there are exceptions. Other languages have different needs, like genders for nouns in German. So it needs a customisable (per language) list of attributes for each noun, and the translation scripts can make use of these. (But maybe this is too complicated, and "Selected: cow" would be adequate. I'm very unsure of this stuff...). I suppose it would also need to handle plurals of non-English unit names - "Train a Triarus" vs "Train five Triarii". Again I'm not sure how :-( |
| 21 | | * '''Scripts''' - a set of Javascript functions, used in the phrases whenever they need something more complicated than simple variable substitution. Date formatting and long number formatting ("Gold: 1,234", or "1.234" or "[wiki:Image:1234.gif]" depending on the language) are necessary for all languages. Other functions depend on the language, such as the construction of "a cow" and "an oak tree". |
| 22 | | |
| 23 | | |
| 24 | | == Users == |
| 25 | | |
| 26 | | * '''Programmers''' - these creatures rarely add text that needs to be translated. It is mostly limited to progress reports while loading, and a few other small things. Don't worry much about them. |
| 27 | | * '''GUI designers''' - probably the main users of complex text. Some simple text is in the XML files, and the rest is generated by Javascript code. They will probably want to write code like |
| 28 | | {{{ |
| 29 | | statusbar.caption = translate("Click to train $n $unit", (shiftKeyDown ? 5 : 1), unit.name); |
| 30 | | |
| 31 | | thing.caption = translate("Saved at $when", savedgame.timestamp); |
| 32 | | }}} |
| 33 | | (at least occasionally). |
| 34 | | |
| 35 | | For the first case, the game will show something like "Click to train 5 archer". To get nicer grammar, they have to provide an English 'translation', like "Click to train [number_word, $n, $unit]" to generate "Click to train an archer" or "Click to train five archers". ("Train: Archer x 5" is much easier; but it seems very ugly, which is why I want a system that is complex enough to do it nicely (and to do that in all languages).) |
| 36 | | |
| 37 | | For the second case, the game will show something useless like "Saved at 1118842121", and they must immediately provide an English translation such as "Saved at [datetime, $when]" (so it knows to call the locale-dependent 'datetime' function). |
| 38 | | |
| 39 | | They need to be able to quickly add strings to the database, and also add/edit (and hopefully test) JS functions (like 'number_word' and 'datetime') when they find they are necessary. |
| 40 | | |
| 41 | | * '''Scenario designers''' - only use simple phrases. They can create the scenario with all English text, and don't need to worry about localisation. |
| 42 | | * '''Translators''' - the only people who need to work in languages other than English. They want a list of all the words and phrases that need to be translated, and as much context as possible (where the string is used, how it's translated into other languages, etc). |
| 43 | | (Problem: How do we get people to actually do this? We presumably can't justify spending any money on it, but it'll be difficult finding somebody who is competent and willing to do a large amount of boring work for free. We should probably optimise the system for them, to make their lives as easy as possible; and also make sure collaboration between multiple translators is possible.) |
| 44 | | * '''Modders''' (including unofficial scenarios) - all of the above. But the majority won't even care about good English grammar (or spelling), so they're probably the least important group. |
| 45 | | * '''Us, making patches''' - like modders, except we do care. But, unlike mods, patches exist in a linear progression (i.e. you can't have the 1.02 updates without the 1.01 updates), so we can just override the existing translation data. |
| 46 | | |
| 47 | | |
| 48 | | == Possible use cases == |
| 49 | | (Warning: slightly vague and probably not entirely helpful.) |
| 50 | | |
| 51 | | '''Programmer''': |
| 52 | | 1. Adds some text to the engine code. |
| 53 | | 1. It's not possible to automatically detect all strings that need to be translated (although that can be automated in special cases), so the programmer opens the list of to-be-translated strings and adds the new one. |
| 54 | | 1. Some time (e.g. weeks) later, they commit everything to SVN, and hope their new string is handled correctly. |
| 55 | | |
| 56 | | '''GUI designer / Scenario designer / Other designer''': |
| 57 | | 1. Adds some simple text to a GUI/scenario/entity/etc XML file (often through an editing tool, rather than manually editing the XML). |
| 58 | | 1. Does nothing, since the text doesn't need any kind of translation yet. |
| 59 | | 1. Eventually, somebody runs a program that extracts all the to-be-translated phrases out of the various types of XML file, which are added to the list which will be given to the translators. |
| 60 | | |
| 61 | | '''GUI designer''' |
| 62 | | 1. Adds some complex text to a GUI script (using Javascript). |
| 63 | | 1. Opens the language editor, adds the new string, adds an English translation, and possibly edits the JS functions which are used in the translation. |
| 64 | | 1. Some time later, commits to SVN, and gets very angry if it loses their translations. |
| 65 | | |
| 66 | | '''Translator''' |
| 67 | | 1. Gets conned into working for us. |
| 68 | | 1. Receives a list of all the phrases that must be translated, and any existing translations (e.g. if someone else has already done part of it). |
| 69 | | 1. Translates as much as they can be bothered to. |
| 70 | | 1. Sends the translated data back to us. |
| 71 | | |
| 72 | | |
| 73 | | == Technical features == |
| 74 | | * Unicode display and input (limited to the BMP, i.e. the first 65536 codepoints). |
| 75 | | * Possibly: support for right-to-left languages (mainly Hebrew). It gets more complicated with bi-directional text (e.g. quoting an LTR English phrase inside an RTL Hebrew phrase) - and the game engine would need to support RTL/bidi text rendering, so maybe this isn't worthwhile. |
| 76 | | |
| 77 | | |
| 78 | | = Miscellaneous i18n stuff = |
| 79 | | == What to translate == |
| 80 | | All text in the game should be translated, except for: |
| 81 | | * Log messages |
| 82 | | * Error messages |
| 83 | | because those are more useful to us than to users, and we wouldn't know what problem they're having if they send us technical error descriptions in Lojban. (The main exception is the "I broke; please report this bug" message in the wdbg crash-detecting system, since that's meant to be seen by the user.) |
| 84 | | |
| 85 | | == Tools == |
| 86 | | Primarily [wiki:Atlas], since most other tools will be used far less often. Its interface doesn't aim to be as 'pretty' as the game, which includes the text; so it seems most convenient to use wxWidgets' standard gettext interface: |
| 87 | | {{{ |
| 88 | | _("Select a unit"); |
| 89 | | |
| 90 | | wxString.format(wxGetTranslation("%d unit selected", "%d units selected", n), n); |
| 91 | | }}} |
| 92 | | The _/wxGetTranslation interface should probably be a wrapper around the game's normal 'translate' system, to avoid having two completely separate systems. Or maybe it's not worthwhile translating the tools anyway... |
| 93 | | |
| 94 | | So, currently undecided. Just use _ for strings that should be translated (and _T for strings that shouldn't), and wxGetTranslation for those that need plural forms, and the underlying implementation can be done later. |
| | 1 | The outdated and incomplete information on this page was removed. See [wiki:Internationalization_and_Localization Internationalization and Localization]. |
