lingo init
Create localization configuration with explicit source, target, and catalog paths.
lingo init writes the localization settings in .lingo/config.json. Use it when a project needs its first source locale, target list, and file patterns. Source files, credentials, and the localization engine binding are separate: initialization does not create or translate those resources.
lingo init --source en --targets de,fr --files 'locales/en.json,docs/en/**/*.md' --yesOpen the generated file and check that it selects only intended source content. Then create those files if necessary, sign in, and run link before remote translation.
Options #
| Option | Default or effect |
|---|---|
--source <locale> | en when accepting defaults. |
--targets <list> | Comma-separated locales; de,fr,es with --yes. |
--files <list> | Comma-separated patterns; locales/<source>.json with --yes, such as locales/en.json. |
--messages-path <path> | Sets React catalog i18n.messagesPath; default locales. |
--types-path <path> | Sets declaration i18n.typesPath; default lingo.d.ts. |
--force | Replaces existing localization settings. |
--no-agents-md | Skips the Lingo.dev block in AGENTS.md and CLAUDE.md. |
--yes, -y | Uses supplied values/defaults without prompts. |
Without --yes, missing choices are prompted. Lists are split on commas and spaces, so add a pattern that contains a space by editing .lingo/config.json. Duplicate targets and the exact source locale are removed. An empty effective target list is rejected. Quote patterns so the shell does not expand them before the CLI receives them.
Init also writes a Lingo.dev block to the project's AGENTS.md, creating the file when it is missing, and to an existing CLAUDE.md unless it imports an AGENTS.md that takes the block. The block tells coding agents to run npx @lingo.dev/cli agent-guide before localization work. Text outside the block's markers is kept, and a later run replaces only the text between them.
Reinitializing an existing project #
Without force, existing localization configuration is preserved and initialization fails rather than overwriting it. With force, the command rebuilds files[] from patterns. Advanced entry options such as exclusions, explicit formats, output templates, and key controls are lost. Preserve them before using force, or edit the existing config for a smaller change.
Other root sections, including the organization/localization engine binding, survive. Catalog path defaults are omitted from the saved config; a force run returning to defaults can clear earlier i18n overrides. Changing catalog paths does not change translation file patterns automatically.
The first-file recipe continues from configuration to initial backfill and retrieved target files. Configuration is the reference for advanced file entries.