Import translations

This guide applies to the branch selected in Current branch. Keys, values, languages, tags and file mappings are independent between branches. See branch navigation and branch permissions.

Import adds branch keys and direct language values from files. It never creates languages, renames existing keys, deletes missing rows, archives content, or automatically changes an existing ICU contract.

Before you start

You need Owner, Admin or Editor in an active workspace, project and branch. Every incoming language must already be active in Languages. Archived keys must be restored by Owner/Admin first. See format compatibility before preparing files.

Limits are 20 files and 20 MiB combined, 10,000 keys and 50,000 language values per job. Each value remains limited to 16 KiB UTF-8. Generic ZIP upload is unsupported. A background worker must be running; see worker setup.

Upload and map

1. Open a project and select Import in its side navigation.
2. Choose Translation files, then Upload and map files. Uploading does not change translations.
3. Select each file’s File format and Language. Use languages declared in the file only when the format carries them explicitly.
4. Keep a consistent File group across later imports and exports of the same resources. It distinguishes independent catalogs with otherwise identical identifiers.
5. For Excel, choose a Worksheet if there is more than one. For CSV/Excel, specify Key column and language columns. Headers such as value:en map directly. Other headers need Add column mapping. Analyse once to discover worksheets and headers, then correct the mappings and generate another preview.
6. Select Text interpretation. JSON and Properties strings default to Plain text; choose ICU explicitly when they contain ICU expressions. Native format declarations and spreadsheet metadata supply their own parameter definitions.
7. For a Localisync CSV export, select Localisync formula-safe export as the CSV profile. Select ISO-8859-1 (legacy) only for a Properties file known to use that encoding. Other input defaults to UTF-8; Apple UTF-16 requires a BOM.

Choose how values change

Fill missing translations is the default. Existing non-Missing values are retained. Select Overwrite existing translations to replace them explicitly.

Empty, null and whitespace-only input preserves an existing value by default. The separate Clear existing translations when an incoming value is empty option clears it; the preview counts those changes. Clearing and overwriting are independent choices.

Keys or values absent from the files stay unchanged. You can select Add tags to imported keys; existing tags are preserved, and table files can also carry tag names. Import does not remove tags. At most 20 tags may result on a key.

Review every change

Select Generate preview. The job moves through queued and processing states, then presents:

• New, changed, cleared, unchanged and skipped value counts.
• Each key’s current and resulting text, language and metadata.
• Blocking errors and warnings with file positions where available.
• Proposed formats and shared variables for new ICU keys.

An external identifier such as a sentence may not be a valid Localisync key. Enter Localisync key for this file identity. Original identifiers, contexts and file containers remain associated with that key. Future imports find the same key even after a panel rename. Different contexts must map to distinct keys.

For positional native placeholders, a contract error shows file and key variable names. Enter an explicit Parameter mapping, for example arg1=person. If a native plural’s selection count and displayed positional count represent the same variable, map both names to it explicitly. Mapped variables must have compatible types. The original positional order is preserved for later native export.

Review inferred contracts, the before/after file notes and any compatibility warnings, then select the corresponding acknowledgement. Notes use the scoped mappings in the format guide; unsupported placements stop the preview. Regenerate preview validates any mapping, contract or acknowledgement change. Editing a preview never silently changes an existing key’s contract; update that key in Translations first when necessary.

Apply and read the result

Apply import is enabled only for the current saved preview with no blocking errors. Its confirmation lists additions, replacements and clears. Confirm to queue the atomic write.

Every affected key and cell is checked again, together with membership, active languages, archives and tags. A conflicting change aborts the whole transaction. A success receipt appears only after translations, identities, tags, history and audit have committed together. Unchanged values gain neither versions nor extra history records.

You can reload the page or return through Your transfers. Jobs belong to their creator; a teammate cannot read your uploaded files or preview. Files and preview content expire after 24 hours. Content-free summaries remain for 30 days.

When an import stops

• Conflict: generate and review a new preview. No partial import is retained.
• Unsupported expression or file: correct the identified record; unsupported content is never converted to plain text silently.
• Missing/inactive language: ask Owner/Admin to configure Languages, then regenerate.
• Temporary dependency failure: the worker retries transient errors. If it stops, use Retry analysis and review again. Retrying does not automatically approve Apply.
• Cancelled: existing translations stay intact. Cancellation is unavailable after atomic recording starts.
• Expired: upload again; expired content cannot be recovered from the job summary.