# Best practices for i18ntranslator > Best practices for i18ntranslator Naming and structure One package per application, not per language A package holds every language of one application. Creating one package per language splits the so… - Page: https://dashboard.nizu.io/knowledge_base/view/233-best-practices-for-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 ## Best practices for i18ntranslator ### Naming and structure #### One package per application, not per language A package holds every language of one application. Creating one package per language splits the source of truth and makes progress impossible to read at a glance. #### Keep namespaces stable A namespace is the origin file, and it becomes the file name on export. Renaming `common` to `general` does not move the keys it creates a second namespace and leaves the first one behind. Decide the file layout before the first import. #### Name the files so the language is obvious `fr.common.json`, `common.fr.json` and `locales/fr/common.json` are all detected automatically. `translations_final_v2.json` is not, and someone will eventually import it as the wrong language. ### The import discipline #### Always preview before importing The preview is computed by the same code that does the write, so the numbers it shows are the numbers you will get. A preview that reports thirty keys removed when you expected none usually means the wrong file, the wrong namespace, or the wrong language. #### Import the source language first Target-language files can only fill keys the source already defines. Importing French into an empty package produces a report full of *no such key in the source language*, and nothing is written correctly, because a translation with no source is not a translation. #### Let the project keep the originals Do not clean out old language files from the project's Files tab. The sequence of uploaded files is the version history of the source material, and every import in this App points back at the exact file it read. ### Placeholders #### Treat a rejection as a real defect The validator refuses a translation that loses or gains a `%s`, `%1$s`, `{count}`, `{{name}}` or an HTML tag. That is not pedantry: an application that runs `sprintf` on a string missing its argument crashes, and it crashes only for the users of that one language, which is exactly where nobody is looking. #### Placeholders may move, not change Word order changes between languages, and the validator allows it it compares which placeholders are present and how many, not where they sit. `%2$s de %1$s` is a perfectly valid translation of `%1$s of %2$s`. #### Only override the check deliberately Managers can save past the validator. The right reason is a genuine source-string bug; the wrong reason is being in a hurry. Every override is recorded in the package history. ### Working with AI #### Write the context prompt properly The AI context is sent with every request and is the single biggest lever on quality. Two useful sentences beat two paragraphs of vague adjectives: *"A B2B logistics dashboard used by warehouse staff. Formal register, address the user politely, keep labels short. 'Shipment' always means a physical consignment, never a document."* #### Never export AI drafts unreviewed AI output is saved as **Draft** for a reason. Machine translation of UI strings is good at grammar and bad at context: it will confidently translate a button label as a full sentence, or a product name as a common noun. Read the drafts, then confirm them. #### Translate in batches you can actually review Running the AI over five thousand keys produces five thousand drafts nobody will read, and they will be confirmed in bulk out of fatigue. Namespace by namespace is a better rhythm. #### Give the operation its own API key Under **Settings → AI → Operations**, the translation operation can have its own provider, key and model. That is how you find out what localisation actually costs, and it lets you use a cheaper model here than for the workspace's other AI features. ### Statuses and review #### Use Reviewed to mean something *Translated* means a person typed it. *Reviewed* should mean a second person signed it off. If everyone marks their own work reviewed, the status stops carrying information and the progress bars start lying. #### Work the Outdated tab after every source import Outdated is the App telling you precisely which translations drifted. It is a short, finite list right after an import; left alone for three releases it becomes the reason a language quietly rots. ### Permissions #### Give translators the minimum A translator needs **Translate strings**, not **Manage**. Manage includes import, export, the GitHub connection and the ability to override the placeholder validator. #### Remember that project access is the outer gate Someone who cannot see the project cannot see its packages, whatever their App permissions say. Add translators to the project, not around it. ### GitHub #### Use a fine-grained token, scoped to the one repository **Contents: read & write** on a single repository is all the App needs. A classic token with full `repo` scope gives it far more than it will ever use. #### Pull before a long translation session Pulling first means you translate the current source text. Pulling after a week of work means discovering that half of it is already outdated. #### Read the conflict list before accepting it The overwrite gate exists because the alternative is silently destroying someone's work. When it appears, open the files on GitHub and look at what changed. Usually a developer added a key by hand in which case pull, import, and push cleanly instead of overwriting. #### Never point the App at a protected production branch Push to a working branch and open a pull request. The App deliberately refuses to force-update a branch that moved underneath it, but it cannot judge whether a commit belongs on `main`. ### Data hygiene - **Keep untranslated keys out of exports** (the default). A missing key falls back to the source language; an empty string renders as a blank label. - **Do not delete a language to "start again"** removing a language deletes every translation in it. Re-import instead. - **Watch the skipped count on imports.** A file full of skipped keys usually means booleans, numbers-as-config or a stale translation file, and it is worth understanding rather than ignoring.