Skip to content

Application. Translations

Jump to bottom
Mr. Fat Guy edited this page May 28, 2024 · 37 revisions

Table of Contents:

Table of contents generated with markdown-toc.

Strings Translations

Implemented in: #27, #53 and #54.

Introduction

We are re-using a translation concept from Yii 2 PHP framework. A separate .json file per each language and translation category that stores translations to given language identified by English translation string.

This solution gives two very important advantages:

  1. Since translation method is called using actual English string, not some kind of weird placeholder (like river-pan-button) it will display that English string, not a placeholder, in case translation is missing or the whole translation mechanism is failing. This produces much more professional effect.
  2. It is much easier to translate each string and file, because you always have English (base) translation on your left side (as a identification key).

Details

We use following rules for our translation system:

  1. One top-level language folder in main repo's folder or somewhere else
  2. Subfolders in this folder that corresponds to each location, i.e. river, assay, bank, credits, etc.
  3. Files in each subfolder matching a language, i.e. en.json, pl.json, de.json, it.json etc.
  4. Each file contains translations in form of simple JSON file where English translation is a key. NOTE: we as well need english to english translation, so each location should have en.json file with translations as well!
  5. Inside your code you have a method that calls translation using group and English translation as a parameters
  6. Current in-game language is checked inside this method so there's no need to use as a parameter in each method's call
  7. If there's a translation missing for given language and/or group and/or string, English translation is always used by default

Groups

To make navigation through translations easier, we have split translation strings into groups:

  • assay
  • bank
  • credits
  • doctor
  • end
  • events
  • health
  • jail
  • mercantile
  • mines
  • newspaper
  • options
  • other
  • river
  • saloon
  • stable
  • startup
  • time

New groups maybe introduced later, if found necessary.

Paths

Translation files are stored in:

/src/language/[group]/[language].json

Where:

For example:

  • /src/language/assay/de.json holds Assay Office's translations for German language and
  • /src/language/bank/en.json has English translations for Bank.

Examples

Example simple translation file for river group and pl language (src/language/river/pl.json):

{
    "Too many items to carry!": "Zbyt wiele przedmiotów do niesienia",
    "Fish": "Łowienie",
    "Water": "Picie",
    "Pan": "Przesiewanie",
    "Exit": "Wyjście",
}

Example simple translation file for river group and en language (src/language/river/en.json):

{
    "Too many items to carry!": "Too many items to carry",
    "Fish": "Fishing",
    "Water": "Drinking",
    "Pan": "Sifting",
    "Exit": "Exit",
}

Example translation file for end group and uk language (src/language/end/uk.json) with multi-line support:

{
    "And so ends the life\\n\\nof yet another poor\\n\\nprospector who, like\\n\\nso many before him,\\n\\ndied looking for but\\n\\nnever finding the...\\n\\n\\n\\nLOST DUTCHMAN MINE": "І так закінчується життя\\n\\nще одного бідного\\n\\nстаратель, який, як\\n\\nтак багато до нього,\\n\\nпомер у пошуках але\\n\\nніколи не знайти...\\n\\n\\n\\nЗАГУБЛЕНА ГОЛЛАНДСЬКА МІНА",
    "Play Again?": "Грай знову?",
    "Yup": "Так",
    "Nope": "ні",
}

For an example call of translation please go to here: Coding → Common Solutions → Translating Texts → Short Strings.

Providing Translations

Since translation files are stored in the repository, as a regular files (that are fed into application during build), adding new translation or correcting existing one is a matter of simple update + commit + push. And can be achieved by anyone.

Only:

  • new groups or new languages
  • changes to existing English translation
  • entirely new translations that introduces new key (new English translation)

Requires developer's attention as it introduces changes to the core code as well.

Translations of Big Blocks of Text

Implemented in: #56.

Introduction

The ability of being able to change big blocks of text (like credits) by me or anyone else other than developer is crucial since we want to run a crowdfunding campaign and award each backer with adding their name or nick at the end of credits text. We strongly believe that we will have a lot of backers and that at some point we will be updating credits file sometimes more often than the rest of code.

Editable big blocks of text or whole-page text will also be used in newspaper.

For big blocs of text we are using Markdown instead of JSON.

Details

We use following rules for our translating whole pages or big blocks of text:

  1. Again, one top-level translations folder in main repo's folder or somewhere else
  2. Again, subfolders in this folder that corresponds to each language, i.e. pl, en, ua, sl, etc.
  3. Again, files in each subfolder matching a group or keyword, i.e. credits, news etc.
  4. Each file is a typical Markdown document this time, not a JSON array / file
  5. Each file is used entirely, as-is (no substitution as in case of "short" translations)
  6. There is no substitution, so if a file is missing an error must be thrown or app compilation must fail
  7. We can use images (added to Markdown document using standard ![]() syntax.
  8. All images used in given document must be stored in corresponding main / group folder.

Images and Languages

Image filename can be anything you like. There's no automatic image file-translation matching. If you want to use the same image in many language versions of given document then you use it in typical way (i.e.: ![niner-games-logo](niner-games.png) added to \en\news.md, \pl\news.md, de\news.md, etc.

If you really, really need a language-specific image then you must create all those images, name them independently and add each to the corresponding document (i.e. put ![title-english](title-english.png) to \en\credits.md, ![title-polish](title-polish.png) to \pl\credits.md and so on).

Markdown

Markdown parser used to parse these documents must be able to at least render:

  1. Basic formatting: bold (**bold**) and italics (_italics_ or *italics*)
  2. Images: ![alt text](filename.ext). Note that we are not using file paths!

It would be great, if we could also have full or at least partial support of the HTML code embedded inside Markdown blocks.

Example

Example Markdown file (part) for credits group and en language (translations\en\credits.md):

Game development and <span style="text-decoration-line: underline">swiss-army-knife</span>:

<span style="font-size: 16px">**Maciej Madejczyk**</span>

![Maciej Madejczyk](madej-pixelized-avatar.png)

The whole idea, design and a <span style="text-decoration-line: underline">nasty dictatorship</span>:

<span style="font-size: 16px">**Tomasz Trejderowski**</span>

![Tomasz Trejderowski](trejder-pixelized-avatar.png)

This example assumes that our Markdown renderer supports embedding regular HTML and CSS inside.

Supported Languages

Implemented in: #49, #50, #81 and in #170.

Ten languages will be supported in game:

English Polish Silesian German Spanish
ISO 639-1 code en pl [sx] de es
AI translation -- Google Translate Silling Translatōr Google Translate Google Translate

There's no specific two-letter code in ISO 639-1 for Silesian (there's only three-letter ISO 639-3 szl code). But since sx is not used and looks cool, we'll use this one.

French Italian Hindi Ukrainian Hebrew
ISO 639-1 code fr it hi uk he
AI Translation Google Translate Google Translate Google Translate Google Translate Google Translate

English language is the default game's language and base for all translations.

All AI-based initially generated translations will be later fixed by professional human translators (see details below).

English

Latin alphabet:

a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, w, v, x, y, z A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, W, V, X, Y, Z

ISO 639-1 language code: en. Link to Wikipedia: Latin script.

English translation is a base one and is mutually provided by @mrfatguy, @MadejaMaciej and @pikbik (GitHub).

Polish

Latin alphabet + language-specific diacritics:

ą, ć, ę, ł, ń, ó, ś, ż, ź Ą, Ć, Ę, Ł, Ń, Ó, Ś, Ż, Ź

ISO 639-1 language code: pl. Link to Wikipedia: Polish language.

English translation is mutually provided by @mrfatguy, @MadejaMaciej and @pikbik (GitHub).

Silesian

Latin alphabet + Polish alphabet + language-specific diacritics:

ã, ẽ, ŏ, ō, ô, õ, ů Ã, Ẽ, Ŏ, Ō, Ô, Õ, Ů

ISO 639-1 language code: sx (unofficial). Link to Wikipedia: Silesian language.

Silesian translation is currently provided by @wadimfiliks, but can also be provided by Paweł.

German

Latin alphabet + language-specific diacritics:

ä, ß, ö, ü Ä, ẞ, Ö, Ü

ISO 639-1 language code: de. Link to Wikipedia: German alphabet

German translation is currently provided by lucasf03, but can be also provided in future by @leticiastalling (Fiverr), who is already making a Spanish translation for us.

Spanish

Latin alphabet + language-specific diacritics:

¿, ¡, á, é, í, ó, ú, ñ ¿, ¡, Á, É, Í, Ó, Ú, Ñ

ISO 639-1 language code: es. Link to Wikipedia: Spanish orthography.

Spanish translation is currently provided by @leticiastalling (Fiverr).

French

Latin alphabet + language-specific diacritics:

à, â, æ, ç, é, è, ê, ë, î, ï, ô, œ, ù, û, ü, ÿ À, Â, Æ, Ç, É, È, Ê, Ë, Î, Ï, Ô, Œ, Ù, Û, Ü, Ÿ

ISO 639-1 language code: fr. Link to Wikipedia: French orthography.

French translation is provided by @pikbik (GitHub), but can be also provided in future by @leticiastalling (Fiverr), who is already making a Spanish translation for us.

Italian

Latin alphabet only.

ISO 639-1 language code: it. Link to Wikipedia: Italian language.

Italian translation is provided by @cinziaborgia (Fiverr).

Hindi

We will be using original Devanagari script (letters):

अ, आ, इ, ई, उ, ऊ, ऋ, ए, ऐ, ओ, औ, क, ख, ग, घ, ङ, च, छ, ज, झ, ञ, ट, ठ, ड, ढ, ण, त, थ, द, ध, न, प, फ, ब, भ, म, य, र, ल, व, श, ष, स, ह

ISO 639-1 language code: hi. Link to Wikipedia: Hindi.

Hindi translation is provided by @sanjeevsoni (Fiverr).

Ukrainian

Cyrylic:

а, б, в, г, ґ, д, е, є, ж, з, и, і, ї, й, к, л, м, н, о, п, р, с, т, у, ф, х, ц, ч, ш, щ, ь, ю, я, ' А, Б, В, Г, Ґ, Д, Е, Є, Ж, З, И, І, Ї, Й, К, Л, М, Н, О, П, Р, С, Т, У, Ф, Х, Ц, Ч, Ш, Щ, Ь, Ю, Я, '

ISO 639-1 language code: uk. Link to Wikipedia: Ukrainian alphabet

Ukrainian translation is provided by @nastyuaya (Fiverr).

Hebrew

פ ,ם ,ן ,ו ,ט ,א ,ר ,ק ,ש ,ד ,ג ,כ ,ע ,י ,ח ,ל ,ך ,ף ,ץ ,ת ,צ ,מ ,נ ,ה ,ב ,ס ,ז.

Please, note that Hebrew is the only right-to-left alphabet and language supported currently in our game.

ISO 639-1 language code: he. Link to Wikipedia: Hebrew alphabet

Hebrew translation is provided by @danielgold848 (Fiverr).

Entire Character Set

For testing purposes here is the entire character set:

a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, w, v, x, y, z
A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, W, V, X, Y, Z
ą, ć, ę, ł, ń, ó, ś, ż, ź Ą, Ć, Ę, Ł, Ń, Ó, Ś, Ż, Ź
ä, ß, ö, ü Ä, ẞ, Ö, Ü
¿, ¡, á, é, í, ó, ú, ñ ¿, ¡, Á, É, Í, Ó, Ú, Ñ
à, â, æ, ç, é, è, ê, ë, î, ï, ô, œ, ù, û, ü, ÿ À, Â, Æ, Ç, É, È, Ê, Ë, Î, Ï, Ô, Œ, Ù, Û, Ü, Ÿ
ã, ẽ, ŏ, ō, ô, õ, ů Ã, Ẽ, Ŏ, Ō, Ô, Õ, Ů
अ, आ, इ, ई, उ, ऊ, ऋ, ए, ऐ, ओ, औ, क, ख, ग, घ, ङ, च, छ, ज, झ, ञ, ट, ठ, ड, ढ, ण, त, थ, द, ध, न, प, फ, ब, भ, म, य, र, ल, व, श, ष, स, ह
а, б, в, г, ґ, д, е, є, ж, з, и, і, ї, й, к, л, м, н, о, п, р, с, т, у, ф, х, ц, ч, ш, щ, ь, ю, я, '
А, Б, В, Г, Ґ, Д, Е, Є, Ж, З, И, І, Ї, Й, К, Л, М, Н, О, П, Р, С, Т, У, Ф, Х, Ц, Ч, Ш, Щ, Ь, Ю, Я, '
פ ,ם ,ן ,ו ,ט ,א ,ר ,ק ,ש ,ד ,ג ,כ ,ע ,י ,ח ,ל ,ך ,ף ,ץ ,ת ,צ ,מ ,נ ,ה ,ב ,ס ,ז

Logo of Niner Games company   Logo of Lost Dutchman Mine game

Home

Game

Town

Locations

Gameplay

Development

Clone this wiki locally