Formats

Find the file handler that translates your text while preserving the structure your application needs.

A locale file contains more than words. Its keys connect messages to code, its placeholders accept application values, and its structure tells a framework how to load the result. A document adds headings, links, examples, and metadata. File translation needs to change the language without losing those connections.

Lingo.dev uses a format handler to select translatable text and reconstruct the result. Choose the handler by what the file means. A Rails catalog and an OpenAPI specification can both end in .yml, but translating every string in either would produce different problems: a Rails locale root must change, while an API's operation identifiers must stay fixed.

Find your format #

SourceHandler kindReference
Nested JSON catalogjsonJSON
JSON with context commentsjsoncJSONC
YAML catalogyamlYAML
YAML with one locale rootyaml-root-keyLocale-root YAML
Static TypeScript locale moduletypescriptTypeScript
Static PHP locale arrayphpPHP
Markdown documentmdMarkdown
Markdown with JSX componentsmdxMDX
Markdoc documentmarkdocMarkdoc
OpenAPI 3.x YAMLyaml-openapiOpenAPI
Android resource XMLandroidAndroid
Flutter Application Resource BundleflutterFlutter ARB
Apple string tablexcode-stringsApple strings
Apple plural-resource plistxcode-stringsdictApple stringsdict
Apple multi-locale catalogxcode-xcstringsApple String Catalogs
Gettext PO catalogpoGettext
XLIFF interchange documentxliffXLIFF
SubRip subtitlessrtSubRip
Plain text, translated line by linetxtPlain text
HTML document or fragmenthtmlHTML
CSV table with a column per localecsvCSV
Java properties resource bundlepropertiesJava properties
Selected Payload CMS fieldspayloadPayload

The references describe the established file handlers, including their extraction and reconstruction limits. The CLI and GitHub App accept the 22 configured kinds above other than Payload. HTML is inferred from .html and .htm; its output preserves untouched source and sets an explicit <html> element's lang to the target locale. Explicitly select the intended YAML variant or Android format in repository configuration. Like Apple String Catalogs, CSV keeps every locale in the source file. The CLI quickstart carries one file through setup and retrieval; GitHub covers the managed repository workflow.

Current provider connections select and write content through their own integration contracts.

To translate structured data directly, submit inline JSON. To upload source files and retain their formats, follow File documents. Both use the same translation-job lifecycle.

Keep the source revision with its translations #

Incremental file translation compares the current source with a previous source and uses the corresponding existing target. Together, those inputs let unchanged messages retain accepted wording while new or changed messages receive translations.

Keys make that comparison useful: checkout.title and account.title can contain identical English text and still retain different translations. Array positions, subtitle cue numbers, plain-text line positions, and document structure also participate in matching. Moving an item or reorganizing a translated document can change the correspondence, so keep targets paired with the source revision from which they were produced.

Most formats produce a separate file for each target locale. Apple String Catalogs instead merge locales into the source file. A Payload artifact or String Catalog can also contain some target values while still missing others. Review the actual target entries, not just whether a file exists.

Control text selection and output separately #

Excluding text from translation can have several meanings. A locked catalog value comes from the source; a preserved value comes from the existing target; an ignored value can disappear from output. The format and calling interface determine which controls are available.

Use CLI key scopes for JSON/JSONC, YAML, locale-root YAML, PHP, and TypeScript. A partial update keeps existing target wording outside the selection, but handling of source-only entries and array positions depends on the format. Inspect the whole result using its format reference.

Context metadata has equally specific behavior. A JSONC @context comment describes the next string value. An ARB @message.description describes its message. Gettext msgctxt distinguishes messages and supplies context. Ordinary comments can survive reconstruction without becoming translation instructions. React's @src and @orphan annotations belong to its catalog-maintenance workflow.

After retrieving a file, load it through the system that uses it. Check the selected locale, variables, plural forms, links, and protected data alongside the translated meaning. The application guides complete that work for web apps, native resources, and static content.