File format compatibility

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.

The file extension selects a family; the content still has to fit the supported subset below. Import reports unsupported content before Apply. Export reports it before exposing a download. An unsupported construct is never flattened into ordinary text silently.

Compatibility matrix

Format	Supported structures	Important boundaries
Android Resources .xml	string, positional string/integer arguments and cardinal plurals	Resource references, arrays and rich markup are rejected. Output names require lowercase letters, digits and underscores, starting with a letter; map other names explicitly.
Apple .strings	Quoted key/value pairs, escapes, string/integer positional arguments	A plural is emitted in a companion .stringsdict. UTF-16 requires a BOM.
Apple .stringsdict	One integer cardinal substitution per key	The cardinal argument must be first. Multiple substitution graphs are rejected. Strings and plural companion files are delivered together when needed.
Apple .xcstrings	Catalog versions 1.0/1.1 input, string units and one cardinal plural variation	Output is version 1.0. Device/width variants and substitution graphs are rejected.
Flutter .arb	Strings, named placeholders, cardinal plurals and selects	Advanced formatter metadata, ordinal plurals and offsets are rejected. Use Flutter use-escaping: true; output escapes literal syntax and renders ICU # as the named count.
Gettext .po, .pot	Message ID, context, C-style positional arguments and verified integer plural profiles	Fuzzy and obsolete entries are rejected. POT is a source-locale template with empty target strings; select only the source language and the empty-string policy. Plurals need distinct singular/plural IDs.
Angular XLIFF .xlf, .xliff	Explicit 1.2/2.0 selection, one segment per unit, simple interpolation placeholders and supported cardinal/select ICU	Source text is required for export. Rich tag placeholders, ordinal plurals and offsets are rejected. Unit IDs, file containers and placeholder attributes are retained.
Key-value JSON .json	Flat/nested objects with string/null leaves	Paths flatten with .. Duplicate properties and path collisions fail. No arrays or numeric/boolean leaves. Choose Plain text or ICU explicitly.
Java .properties	Escapes, separators, continuation lines and Unicode escapes	UTF-8 by default; explicit ISO-8859-1 legacy input. Preceding and trailing comments are retained. No automatic encoding guess.
Rails YAML .yml, .yaml	Locale roots, nested string keys, %{name} arguments and category plurals	Arrays, aliases, anchors and explicit YAML tags are rejected. Nested key collisions fail.
.NET .resx	String resources and simple indexed parameters	Binary/object data, alignment/advanced formatters and native plurals are rejected.
CSV .csv	Key and locale columns, optional format/parameter/tag metadata	Comma-separated, quoted records, UTF-8. Choose the correct formula-safe/raw import profile.
Excel .xlsx, .xls	The same table model with worksheet selection	String cells only. Formula cells, macros, encrypted files and executable content are rejected; cells are never evaluated.

For native plural conversion, the common supported subset is one cardinal variable and category branches (zero, one, two, few, many, other). other is required. Native formats that cannot represent select, selectordinal, offsets, exact-number matches or nested plurals reject them. Formats carrying ICU directly, including JSON/tables, preserve the supported editor ICU syntax. Flutter and Angular have the narrower constraints listed above.

Identity and parameter preservation

A Localisync key is not automatically renamed to satisfy a file format. Import binds original identifier + context + file group + container to an internal key. Select the same group on subsequent transfers. Gettext sentences and generated XLIFF IDs can therefore retain their external identity while using a readable internal key name.

Native positional arguments need an explicit order unless a previous import recorded it. The preview can map native arg1 to a named key variable such as person. This mapping does not edit an existing contract. Numeric selection variables remain numeric; incompatible types cause an error. An export mapping affects only the file.

Plain text containing native formatting syntax (for example %@, %{name} or {0}) is rejected where the format cannot distinguish it from a parameter. Escaped ICU syntax that cannot be preserved in Angular XLIFF is also rejected. Use an explicit supported contract or JSON/tables for those values.

Supported native notes are retained as separately scoped, editable context. Import previews show current and proposed notes; Apply commits notes and values together and rejects a changed key revision. Reimport replaces only the matching format/file group/key/language note scope, preserving other notes and the shared description. A note-only update does not invalidate a text review.

• ARB: message descriptions and placeholder descriptions/examples (example JSON types are retained).
• XCStrings: key comments. External review states never create a Localisync human review.
• XLIFF: unit notes and file notes, including their attributes; 1.2 header notes are retained. Group note placement and XML comments require explicit normalization to supported note elements.
• PO/POT: translator/extracted comments, references, previous-message notes and flags. Fuzzy/obsolete restrictions still apply.
• RESX: data comment elements. Map XML comments to those elements before importing.
• Android: resource comments, plural-item comments and file comments. Comments embedded inside translated text are rejected as ambiguous.
• Apple strings: preceding and trailing comments. Stringsdict retains comments around resource keys/dictionaries and file boundaries; nested substitution comments require explicit normalization before import.
• Properties and YAML: comments retain their scope; YAML retains key/value placement and plural-branch comments.
• CSV/XLSX/XLS: the optional description column becomes a scoped file note.

Context limits are 100 notes per key, 16 KiB UTF-8 per note and 1 MB including metadata. Unsupported native note placement stops the import rather than silently discarding it. An export that cannot carry applicable notes in its selected format and file group stops with context_loss before offering a download. The shared key description can be exported to a table; if it conflicts with a table description note, resolve that conflict first. No automatic conversion combines unrelated notes into one description.

File semantics such as Gettext context, plural identity and placeholder ordering remain separate from notes.

Table columns

The default header is:

key,format,parameters,tags,description,value:en,value:tr

key is required. Map other column labels explicitly. format is plain or icu; parameters is a JSON array of { "name": "count", "type": "number" } declarations, and tags is a JSON array of tag names. description is optional plain-text context. These metadata columns are optional for external imports. Columns beginning with value: map to that project locale without inferring a language from a filename.

An XLSX/XLS file with one worksheet selects it automatically. Multiple worksheets require a choice; only the selected sheet is imported. The current table bound is 10,000 data rows, 256 columns and 50,000 mapped language values. Excel numeric cells must be converted to Text when the intended translation is a number string.

Gettext plural profiles

The current verified integer profiles cover en, de, es, it, nl, sv, no, da, fi, el, pt, bg, et, he, fr, tr, ja, ko, zh, th, vi, id, ru, uk, pl, cs, sk and ar. Regional locales use their language profile, except pt/pt-BR use the n > 1 rule and pt-PT uses n != 1. Each message is also checked against locale categories; profiles that would merge distinct branches are rejected. Imported Plural-Forms must match the supported canonical rule; arbitrary executable expressions are never evaluated. Unsupported locale/rule combinations stop the import/export.

The profile’s category order maps Gettext indexes to ICU branches. A native integer format cannot express all fractional ICU distinctions; use an ICU-carrying format when your application requires those distinctions. See GNU Gettext’s entry specification.

Size and safety boundaries

• Upload: 20 files, 20 MiB combined. Text values: 16 KiB UTF-8 each.
• Import/export: 10,000 keys and 50,000 selected language values. No partial processing on overflow.
• Expanded XLSX data and generated output: 100 MiB. Spreadsheet archives also have entry/path checks.
• JSON/XML nesting: at most 32 levels. ICU retains the editor’s 32 variables, 10 nested expressions and 1,000 AST nodes.
• Parser: separate process, 30 seconds, 256 MiB JavaScript heap, 512 MiB RSS guard. Split a file if it exceeds the processing budget.

Files stay in private storage and expire after 24 hours. See worker and storage setup for operations and retention.

Native application integration

Android output uses values/strings.xml for the source and BCP 47 resource directories for other locales. Apple output uses locale .lproj folders or a combined catalog. Flutter output uses app_<locale>.arb and requires escaping enabled in l10n.yaml:

use-escaping: true

The generated files are localization resources for your platform tooling, not Localisync SDK bundles. Refer to Flutter localization configuration and Angular translation file formats for integration into those applications. These exported resources are separate from immutable releases and SDK bundles. See publishing, the Web SDK and the Flutter SDK for application delivery.