Translating Mods

Introduction

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.

Pre-Requisites

• SVN or Git Installation see ​wiki:GettingTheCode
• Python 3+ (Added to PATH)
• A text editor
• A little modding experience see ​wiki:Modding_Guide
• A little command line experience

Setup

Note: You need SVN or Git for the extraction tools.

• Create a mod named MyMod in your clone of the repository in the following folder

  binaries/data/mods
  

• Add a mod.json. More information ​here

  {
      "name": "MyMod",
      "version": "",
      "label": "MyMod",
      "url": "",
      "description": "A simple mod to test translations.",
      "dependencies": []
  }
  

• Create the following directory tree

  simulation/templates/units
  

• Add a file called my_unit.xml with the following content

  <?xml version="1.0" encoding="utf-8"?>
  <Entity parent="merc_inf|hoplite|template_unit_champion_infantry_spearman">
    <Identity>
      <GenericName>My Unit</GenericName>
      <SpecificName>My Unit's Fancy Name</SpecificName>
      <History>My Unit was a really important unit.</History>
      <Icon>units/samnite_spearman.png</Icon>
    </Identity>
    <VisualActor>
      <Actor>units/carthaginians/infantry_spearman_c_samnite.xml</Actor>
    </VisualActor>
  </Entity>
  

• Create the following directory tree

l10n

• Place the ​messages.json file from the public mod in it.

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.

Open the file and replace public- by mymod- e.g.

    {
        "output": "public-civilizations.pot",
        "inputRoot": "..",
        "project": "0 A.D. — Empires Ascendant",
        "copyrightHolder": "Wildfire Games",
        "rules": [
            {
                "extractor": "json",
                "filemasks": [
                    "simulation/data/civs/**.json"
                ],
                "options": {
                    "keywords": [
                        "Name",
                        "Description",
                        "History",
                        "Special",
                        "AINames"
                    ]
                }
            }
        ]
    }

becomes

    {
        "output": "mymod-civilizations.pot",
        "inputRoot": "..",
        "project": "My Mod's Project",
        "copyrightHolder": "My Mod's Copyright Holder",
        "rules": [
            {
                "extractor": "json",
                "filemasks": [
                    "simulation/data/civs/**.json"
                ],
                "options": {
                    "keywords": [
                        "Name",
                        "Description",
                        "History",
                        "Special",
                        "AINames"
                    ]
                }
            }
        ]
    }

TODO: Transifex .tx file.

Extracting the strings

• Go to the following folder with a terminal

  source/tools/i18n
  

• Install the required packages

  pip install -r requirements.txt
  or 
  pip3 install -r requirements.txt
  

• Run

  python updateTemplates.py
  or 
  python3 updateTemplates.py
  

This will parse all the mods in binaries/data/mods/ and generate translation files.

Since our mod has only one unit you can then open l10n/mymod-templates-units.pot File should look like something like this.

# Translation template for My Mod's Project.
# Copyright (C) 2021 My Mod's Copyright Holder
# This file is distributed under the same license as the My Mod's Project project.
msgid ""
msgstr ""
"Project-Id-Version: My Mod's Project\n"
"POT-Creation-Date: 2021-11-03 21:29+0009\n"
"PO-Revision-Date: 2021-11-03 21:29+0009\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit"

#: simulation/templates/units/samnite_spearman.xml:4
msgid "My Unit"
msgstr ""

#: simulation/templates/units/samnite_spearman.xml:5
msgid "My Unit's Fancy Name"
msgstr ""

#: simulation/templates/units/samnite_spearman.xml:6
msgid "My Unit was a really important unit."
msgstr ""

Adding translations

• 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

{lang_code}.mymod-templates-units.po # No final T

e.g for a spanish translation

es.mymod-templates-units.po

Then you can translate in the file directly or use external tools like [POEDIT](​https://poedit.net/)

Translated file could look like this

# Translation template for My Mod's Project.
# Copyright (C) 2021 My Mod's Copyright Holder
# This file is distributed under the same license as the My Mod's Project project.
# Translators:
# First Name Last Name <email>, 2021
msgid ""
msgstr ""
"Project-Id-Version: My Mod's Project\n"
"POT-Creation-Date: 2021-11-03 21:29+0009\n"
"PO-Revision-Date: 2021-11-03 21:29+0009\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit"

#: simulation/templates/units/samnite_spearman.xml:4
msgid "My Unit"
msgstr "Mi Unidad"

#: simulation/templates/units/samnite_spearman.xml:5
msgid "My Unit's Fancy Name"
msgstr "El nombre de fantasía de mi unidad"

#: simulation/templates/units/samnite_spearman.xml:6
msgid "My Unit was a really important unit."
msgstr "Mi unidad era una unidad realmente importante."

Note: It is easy to have conflicts for files like this, so make sure you have backups or use versionning.

The game should automatically read those files and replace the strings with the ones you translated.

Setuping a transifex project

TODO.