Configuration

The localingos.config.json and .localingos.json fields, plus the eight supported catalogue formats and their aliases.

Config files

Running localingos init creates two files:

localingos.config.json — commit this to your repo. Contains project settings shared with your team and CI.

{
  "projectId": "a3b7c9d1-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "sourceLocale": "en-US",
  "format": "json-nested",
  "sourceFile": "src/i18n/en-US.json",
  "outputDir": "src/i18n",
  "outputPattern": "{locale}.json"
}

.localingos.json — add to .gitignore. Contains your API key for local development only.

{
  "apiKey": "your-api-key"
}

The CLI merges both files. In CI, the API key comes from the LOCALINGOS_API_KEY environment variable instead.

Field reference

Field	Type	Description
`apiKey`	string	API key from the Localingos dashboard. Lives in .localingos.json (gitignored) or LOCALINGOS_API_KEY env var.
`apiKeyEnv`	string	Optional. Custom env var name for the API key (for monorepos with multiple projects). Defaults to LOCALINGOS_API_KEY.
`projectId`	UUID	The target project to sync with.
`sourceLocale`	string	BCP 47 locale code for your source language, e.g. "en-US".
`format`	string	Catalogue format. See the format table below — "json-nested" is the default and suits most JavaScript projects.
`sourceFile`	path	Relative path to your source locale catalogue.
`outputDir`	path	Directory where translation files are written.
`outputPattern`	string	Filename pattern for output files. Use {locale} as a placeholder, e.g. "{locale}.json" or "{locale}/LC_MESSAGES/django.po".

Supported formats

Set format to whichever your framework already uses — the CLI reads and writes these natively, so there is no conversion step in your build.

format	Files	Notes
`json-nested`	.json	Hierarchical keys — a.b.c becomes nested objects. The default, and what react-i18next, vue-i18n, svelte-i18n and next-intl expect.
`json-flat`	.json	Dot-separated keys kept flat at the top level.
`yaml`	.yml / .yaml	Nested YAML with no locale root key.
`yaml-rails`	.yml	Rails-style YAML where everything hangs off a locale root (en:). The root is stripped on read so your ids stay locale-free, and restored with the target locale on write.
`properties`	.properties	Java / Spring resource bundles. Flat keys, UTF-8, with \n, \uXXXX and line-continuation escapes handled.
`csv`	.csv	Requires a header row with key and text columns; an optional description column is used as translator context, so no sidecar is needed.
`po`	.po	gettext, as used by Django and Flask. Keys come from msgctxt when present, otherwise msgid. Translator comments (#.) round-trip as descriptions. Plural entries (msgid_plural) are skipped and reported rather than flattened.
`arb`	.arb	Flutter Application Resource Bundles. @key.description supplies translator context, @@locale is written for you, and @key metadata such as placeholders is preserved so flutter gen-l10n keeps working.

Aliases are accepted where they are unambiguous: json → json-nested, yml → yaml, rails → yaml-rails, gettext → po, flutter → arb.

ICU MessageFormat is not a format setting. ICU syntax lives inside your strings and is preserved whichever catalogue format you pick. Note that translation returns the same number of plural forms it was given — it does not expand a two-form source into a language's full CLDR category set.