Your own language and language pack: translation, files, packing

Your language is not in the catalogue? You can add it yourself, and no programming is needed: a language is only translations, not a single line of code. There are two ways. The first is right in the panel: download the sample, translate it, upload it. The second is a ready-made pack (a .zip file) that can be installed on any Nex1on site, yours or someone else's.

Way one: through the panel

Languages and texts → Languages → Add a language. Fill in the form:

The language is created as a draft: it is not visible on the site yet. Then there are three steps on the language's own page.

1. Download the sample. The “Download all keys” button gives a JSON file with every string of the engine and modules in English. Later, when part of it is already translated, “Download only what is missing” gives only what is not there yet.
2. Translate and upload. The file is built like this: at the top _meta (service data, do not change it), below it strings, “key”: “English text”. Change only the values on the right. Upload the file with the “Upload and check” button (up to 3 MB). An upload adds to the earlier one, so you can translate in parts.
3. Turn it on. When the translation is ready, press “Turn on”: the language appears in the language choice on the site and in the panel language. A complete translation (100 %) is turned on at once; from 90 % it is turned on with a tick: what is missing is shown in English.

{
    "_meta": { "format": 1, "language": "fr", "base": "en", "keys": 15628 },
    "strings": {
        "ai.bar.label": "Assistant IA",
        "ai.bar.run": "Lancer"
    }
}

What is checked on upload. The file is parsed string by string. Unknown keys are ignored. A string is rejected, with the reason written in the list under the form, if it:

• lost a placeholder in curly braces ({count}, {name}): in the translation they must stay exactly as in the English text;
• gained HTML-like markup or a dangerous link;
• has the wrong number of forms in a string with a number: forms are written separated by “|”, as many as the language rule has;
• has a value that is not text or is longer than 4000 characters.

Deleting. First turn the language off, then “Delete the language” and type its code. The translation files are moved aside to _trash, not erased; site records in this language keep their text.

Way two: a language pack

A pack is for giving a language to others or installing it on several of your own sites: it is a single .zip file. Inside there is only the language description and the translations:

language.json
locales/de.json
modules/news/locales/de.json
modules/forum/locales/de.json

• language.json — language description, placed in the archive root.
• locales/de.json — engine translations.
• modules/news/locales/de.json — translations of the “news” module: one file per module, optional.

No other files may be in the pack: any extra file means the whole archive is refused. A folder named after the pack is not needed; the files lie right in the archive root.

{
    "code": "de",
    "name": "German",
    "native": "Deutsch",
    "direction": "ltr",
    "plural": "en",
    "version": "1.0.0",
    "engine_min": "0.9.9"
}

A translation file is a plain JSON object “key”: “text”, the same format as the engine's locales/en.json: take the keys from there. For a module it is modules/<module name>/locales/<code>.json, with the keys from its en.json. Modules that are not on the site are not touched by the pack.

The rules for values are the same as for an upload in the panel: strings only, up to 4000 characters, {…} placeholders as in English, plural forms separated by “|”. In addition, for a pack: keys only from Latin letters, digits, dot, underscore and hyphen, nesting no deeper than eight levels, no more than 40,000 strings in a file, no HTML-like markup and no links like javascript:. The engine core translation file locales/<code>.json is required.

If the language lives in the engine sources (you have locales/<code>.json and modules/*/locales/<code>.json), the pack is built by a command:

php nex1on language:pack pl --version=1.0.0

It builds nex1on-language-pl-1.0.0.zip, checks every file before packing just as the installer does, and prints the path (by default nex1on-moduli two levels above the site folder; change it with --out=<folder> or app.release_directory in config/local.php). English is not released as a pack: it ships with the engine.

How to install a pack

Add-ons → Modules → Install from archive, choose “Language pack”, upload the file, read the report and install. The details are in the article “Installing your own add-on”. After installing, the language stays off: turn it on on the “Languages” page. English and the site's main language cannot be replaced by a pack. A language that ships with the engine is replaced only by a pack signed by Nex1on with a version not lower than the installed one.

Errors