# 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. (Apps: i18ntranslator) - Page: https://dashboard.nizu.io/knowledge_base/view/231-how-to-use-i18ntranslator - Part of: [Knowledge base](https://dashboard.nizu.io/knowledge_base/llms.txt) on NIZU — https://dashboard.nizu.io/llms.txt - Updated: 2026-11-13T15:10:04Z ## 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.