= Translating Mods

[[TOC]]

== 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 [https://trac.wildfiregames.com/wiki/BuildInstructionsGettingTheCode wiki:GettingTheCode]
- Python 3+ (Added to PATH)
- A text editor
- A little modding experience see [https://trac.wildfiregames.com/wiki/Modding_Guide 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 [https://trac.wildfiregames.com/wiki/Modding_Guide#Howtomakeyourmodshowupinthemodselectionscreen here]
{{{#!json
{
	"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
<?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 [https://trac.wildfiregames.com/browser/ps/trunk/binaries/data/mods/public/l10n/messages.json 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.

{{{#!json
    {
        "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

{{{#!json
    {
        "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
{{{#!python
pip install -r requirements.txt
or 
pip3 install -r requirements.txt
}}}
- Run
{{{#!python
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.

{{{#!pot
# 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

{{{#!pot
# 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.