How to use i18ntranslator

This walks the whole loop once: create a package, get the source strings in, translate them, and get the files back out.

Step 1 — Create a package

1. Open i18ntranslator in the left menu.
2. Click Add package.
3. Fill in:
   • Title — the name of the application being translated.
   • Project — required. This is where the source files are stored and where their history is kept.
   • Source language — the language the application is written in. This cannot be changed once keys have been imported.
   • Context for the AI — optional but worth writing. Two sentences describing the app, its audience and the tone go a long way: "A B2B logistics dashboard used by warehouse staff. Formal register, address the user politely, keep labels short."
4. Save.

Step 2 — Put the language files in the project

The App has no uploader. Files arrive through the project, and only then can they be imported.

1. Open the project the package belongs to.
2. Go to its Files tab.
3. Upload the .json language files.

Name them so the language is recognisable. All of these are understood automatically:

• en.json
• en.common.json — language first
• common.en.json — language last
• locales/fr-BE/common.json — language from the folder

The detected language is only a suggestion; you confirm it before anything is written.

Step 3 — Import the source language

1. Open the package and click Import.
2. Pick the source-language file from the list of the project's .json files.
3. Check the language code and the namespace. The namespace becomes the file name on export, so common exports back to common.json.
4. Click Preview. Nothing has been written yet — this shows exactly what the import will do.
5. If it looks right, click Import.

Repeat for each source file. A package with three source files has three namespaces.

Step 4 — Add the target languages

On the package page, click Add language and pick a code (fr, fr-BE, pt-BR, zh-Hant…). Each language gets its own card with a progress bar.

If you already have partial translations, import those files the same way as in step 3 — choose the target language instead of the source one. Keys that do not exist in the source language are reported and skipped rather than invented.

Step 5 — Translate

Click Translate on a language card to open the editor.

The grid

Each row is one key: its name, the source text, the field you type into, and its status. The tabs across the top filter by status and show a live count for each: All, Untranslated, Outdated, Draft, Translated, Reviewed.

Working quickly

• Start on the Untranslated tab.
• Ctrl/Cmd + Enter saves and jumps to the next row that still needs work.
• Esc discards what you typed in the current field.
• The arrow icon on a row copies the source into the translation — the fastest way to handle a value that must not be translated.
• The search box looks in keys, source text and translations at once.
• Only changed rows are saved, and the footer always shows how many are pending.

Translating with AI

1. Choose a filter tab, or tick specific rows.
2. Click Translate with AI.
3. Wait. The result says how many were translated and how many were rejected.

AI results are saved as Draft and carry a small sparkle icon. Read them, fix what needs fixing, select them and click Confirm draft. Nothing exports as finished work until a person has confirmed it.

When a translation is refused

If a translation loses or gains a placeholder, the row turns red and says exactly what is wrong — for example Placeholder mismatch — Missing: %s. The row stays unsaved so you can fix it; the other rows in the same save go through normally.

This is the App's most important rule. A missing %1$s is not a typo, it is a crash in the application being translated.

Reviewing

A user with the review permission can select rows and click Mark as reviewed. Reviewed is the top status and is what a "this language is finished" claim should mean.

History

The clock icon on a row shows every change ever made to that string: the old value, the new value, who did it, when, and whether it came from a person, the AI, an import or GitHub. Any previous value can be restored.

Step 6 — When the source text changes

Upload the new source file to the project and import it again. The preview will report:

• New keys — added, untranslated everywhere.
• Values updated — the source text changed.
• Marked outdated — existing translations of the changed keys, now flagged.
• Keys removed — no longer in the source file. They are hidden, never deleted.

Translators then work the Outdated tab, which is exactly the list of what drifted.

Step 7 — Export

1. Click Export on the package.
2. Choose a format:
   • JSON — for the application, and the only format that can be imported back.
   • gettext .po — for a gettext toolchain.
   • PHP language file — for a PHP application.
3. Tick the languages you want.
4. Click Download. One file downloads directly; several arrive as a ZIP.

By default, untranslated keys are left out of the export so the application falls back to its own source language — a missing key renders as English, an empty string renders as a blank label. You can change this per package.

Step 8 — GitHub (optional)

1. Click GitHub on the package.
2. Fill in owner, repository, branch and the path template, for example locales/{locale}/{namespace}.json.
3. Paste a fine-grained personal access token with Contents: read & write.
4. Save, then click Test connection.

Pull from GitHub fetches the matching files, saves each one into the project's Files, and imports them — the same path a file you upload yourself takes.

Push to GitHub commits the selected languages as one commit.

If the repository changed

If someone edited those files in the repository since the last sync, the push stops and lists every file that moved, with a link to each. To continue you must tick "I understand this will overwrite the changes made in the repository". Your version then replaces the repository content, and the acknowledgement is recorded in the package history with your name, the time and the resulting commit.

Tips

• Import the source language first. A target file imported into an empty package has nothing to attach to.
• Keep namespaces stable. Renaming one creates a second set of keys rather than moving the first.
• Write the AI context once, properly. It is the single biggest lever on machine-translation quality.
• Do not export a language straight after an AI run — confirm the drafts first.