| 1 | = Translating Mods |
| 2 | |
| 3 | [[TOC]] |
| 4 | |
| 5 | == Introduction |
| 6 | |
| 7 | This guide is intended for people who are already familiar with modding and want to take it up a notch to add i18n (internationalization) to their mods. |
| 8 | |
| 9 | |
| 10 | == Pre-Requisites |
| 11 | |
| 12 | - SVN or Git Installation see [https://trac.wildfiregames.com/wiki/BuildInstructionsGettingTheCode wiki:GettingTheCode] |
| 13 | - Python 3+ (Added to PATH) |
| 14 | - A text editor |
| 15 | - A little modding experience see [https://trac.wildfiregames.com/wiki/Modding_Guide wiki:Modding_Guide] |
| 16 | - A little command line experience |
| 17 | |
| 18 | == Setup |
| 19 | |
| 20 | **Note**: You need SVN or Git for the extraction tools. |
| 21 | |
| 22 | - Create a mod named `MyMod` in your clone of the repository in the following folder |
| 23 | {{{ |
| 24 | binaries/data/mods |
| 25 | }}} |
| 26 | - Add a mod.json. More information [https://trac.wildfiregames.com/wiki/Modding_Guide#Howtomakeyourmodshowupinthemodselectionscreen here] |
| 27 | {{{#!json |
| 28 | { |
| 29 | "name": "MyMod", |
| 30 | "version": "", |
| 31 | "label": "MyMod", |
| 32 | "url": "", |
| 33 | "description": "A simple mod to test translations.", |
| 34 | "dependencies": [] |
| 35 | } |
| 36 | }}} |
| 37 | |
| 38 | - Create the following directory tree |
| 39 | {{{ |
| 40 | simulation/templates/units |
| 41 | }}} |
| 42 | - Add a file called my_unit.xml with the following content |
| 43 | {{{#!xml |
| 44 | <?xml version="1.0" encoding="utf-8"?> |
| 45 | <Entity parent="merc_inf|hoplite|template_unit_champion_infantry_spearman"> |
| 46 | <Identity> |
| 47 | <GenericName>My Unit</GenericName> |
| 48 | <SpecificName>My Unit's Fancy Name</SpecificName> |
| 49 | <History>My Unit was a really important unit.</History> |
| 50 | <Icon>units/samnite_spearman.png</Icon> |
| 51 | </Identity> |
| 52 | <VisualActor> |
| 53 | <Actor>units/carthaginians/infantry_spearman_c_samnite.xml</Actor> |
| 54 | </VisualActor> |
| 55 | </Entity> |
| 56 | }}} |
| 57 | - Create the following directory tree |
| 58 | |
| 59 | {{{ |
| 60 | l10n |
| 61 | }}} |
| 62 | |
| 63 | - Place the [https://trac.wildfiregames.com/browser/ps/trunk/binaries/data/mods/public/l10n/messages.json messages.json] file from the public mod in it. |
| 64 | |
| 65 | **Note** : We copy that file because most mods have the same structure and a such can be extracted the same. If your mod has different folders the messages.json file might need adjustments. |
| 66 | |
| 67 | Open the file and replace `public-` by `mymod-` e.g. |
| 68 | |
| 69 | {{{#!json |
| 70 | { |
| 71 | "output": "public-civilizations.pot", |
| 72 | "inputRoot": "..", |
| 73 | "project": "0 A.D. — Empires Ascendant", |
| 74 | "copyrightHolder": "Wildfire Games", |
| 75 | "rules": [ |
| 76 | { |
| 77 | "extractor": "json", |
| 78 | "filemasks": [ |
| 79 | "simulation/data/civs/**.json" |
| 80 | ], |
| 81 | "options": { |
| 82 | "keywords": [ |
| 83 | "Name", |
| 84 | "Description", |
| 85 | "History", |
| 86 | "Special", |
| 87 | "AINames" |
| 88 | ] |
| 89 | } |
| 90 | } |
| 91 | ] |
| 92 | } |
| 93 | }}} |
| 94 | becomes |
| 95 | |
| 96 | {{{#!json |
| 97 | { |
| 98 | "output": "mymod-civilizations.pot", |
| 99 | "inputRoot": "..", |
| 100 | "project": "My Mod's Project", |
| 101 | "copyrightHolder": "My Mod's Copyright Holder", |
| 102 | "rules": [ |
| 103 | { |
| 104 | "extractor": "json", |
| 105 | "filemasks": [ |
| 106 | "simulation/data/civs/**.json" |
| 107 | ], |
| 108 | "options": { |
| 109 | "keywords": [ |
| 110 | "Name", |
| 111 | "Description", |
| 112 | "History", |
| 113 | "Special", |
| 114 | "AINames" |
| 115 | ] |
| 116 | } |
| 117 | } |
| 118 | ] |
| 119 | } |
| 120 | }}} |
| 121 | |
| 122 | TODO: Transifex .tx file. |
| 123 | |
| 124 | == Extracting the strings |
| 125 | |
| 126 | - Go to the following folder with a terminal |
| 127 | {{{ |
| 128 | source/tools/i18n |
| 129 | }}} |
| 130 | - Install the required packages |
| 131 | {{{#!python |
| 132 | pip install -r requirements.txt |
| 133 | or |
| 134 | pip3 install -r requirements.txt |
| 135 | }}} |
| 136 | - Run |
| 137 | {{{#!python |
| 138 | python updateTemplates.py |
| 139 | or |
| 140 | python3 updateTemplates.py |
| 141 | }}} |
| 142 | This will parse all the mods in `binaries/data/mods/` and generate translation files. |
| 143 | |
| 144 | Since our mod has only one unit you can then open `l10n/mymod-templates-units.pot` |
| 145 | File should look like something like this. |
| 146 | |
| 147 | {{{#!pot |
| 148 | # Translation template for My Mod's Project. |
| 149 | # Copyright (C) 2021 My Mod's Copyright Holder |
| 150 | # This file is distributed under the same license as the My Mod's Project project. |
| 151 | msgid "" |
| 152 | msgstr "" |
| 153 | "Project-Id-Version: My Mod's Project\n" |
| 154 | "POT-Creation-Date: 2021-11-03 21:29+0009\n" |
| 155 | "PO-Revision-Date: 2021-11-03 21:29+0009\n" |
| 156 | "Plural-Forms: nplurals=2; plural=(n != 1)\n" |
| 157 | "MIME-Version: 1.0\n" |
| 158 | "Content-Type: text/plain; charset=utf-8\n" |
| 159 | "Content-Transfer-Encoding: 8bit" |
| 160 | |
| 161 | #: simulation/templates/units/samnite_spearman.xml:4 |
| 162 | msgid "My Unit" |
| 163 | msgstr "" |
| 164 | |
| 165 | #: simulation/templates/units/samnite_spearman.xml:5 |
| 166 | msgid "My Unit's Fancy Name" |
| 167 | msgstr "" |
| 168 | |
| 169 | #: simulation/templates/units/samnite_spearman.xml:6 |
| 170 | msgid "My Unit was a really important unit." |
| 171 | msgstr "" |
| 172 | }}} |
| 173 | |
| 174 | == Adding translations |
| 175 | |
| 176 | - To add a translation for a specific file and a specific language you need to create a copy of the pot file you want to translate. The file should be named as follows for `mymod-templates-units.pot` |
| 177 | |
| 178 | {{{ |
| 179 | {lang_code}.mymod-templates-units.po # No final T |
| 180 | }}} |
| 181 | e.g for a spanish translation |
| 182 | {{{ |
| 183 | es.mymod-templates-units.po |
| 184 | }}} |
| 185 | |
| 186 | Then you can translate in the file directly or use external tools like [POEDIT](https://poedit.net/) |
| 187 | |
| 188 | Translated file could look like this |
| 189 | |
| 190 | {{{#!pot |
| 191 | # Translation template for My Mod's Project. |
| 192 | # Copyright (C) 2021 My Mod's Copyright Holder |
| 193 | # This file is distributed under the same license as the My Mod's Project project. |
| 194 | # Translators: |
| 195 | # First Name Last Name <email>, 2021 |
| 196 | msgid "" |
| 197 | msgstr "" |
| 198 | "Project-Id-Version: My Mod's Project\n" |
| 199 | "POT-Creation-Date: 2021-11-03 21:29+0009\n" |
| 200 | "PO-Revision-Date: 2021-11-03 21:29+0009\n" |
| 201 | "Plural-Forms: nplurals=2; plural=(n != 1)\n" |
| 202 | "MIME-Version: 1.0\n" |
| 203 | "Content-Type: text/plain; charset=utf-8\n" |
| 204 | "Content-Transfer-Encoding: 8bit" |
| 205 | |
| 206 | #: simulation/templates/units/samnite_spearman.xml:4 |
| 207 | msgid "My Unit" |
| 208 | msgstr "Mi Unidad" |
| 209 | |
| 210 | #: simulation/templates/units/samnite_spearman.xml:5 |
| 211 | msgid "My Unit's Fancy Name" |
| 212 | msgstr "El nombre de fantasía de mi unidad" |
| 213 | |
| 214 | #: simulation/templates/units/samnite_spearman.xml:6 |
| 215 | msgid "My Unit was a really important unit." |
| 216 | msgstr "Mi unidad era una unidad realmente importante." |
| 217 | }}} |
| 218 | |
| 219 | **Note**: It is easy to have conflicts for files like this, so make sure you have backups or use versionning. |
| 220 | |
| 221 | The game should automatically read those files and replace the strings with the ones you translated. |
| 222 | |
| 223 | == Setuping a transifex project |
| 224 | |
| 225 | TODO. |
| 226 | |
| 227 | |
| 228 | |