> ## Documentation Index > Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt > Use this file to discover all available pages before exploring further. # run > Plan and execute local translation generation from configured source files. ## Usage ```bash theme={null} hyperlocalise run [--config ] [--group ] [--bucket ] [--file ] [--locale ] [--dry-run] [--workers ] [--output ] [--experimental-context-memory] [--context-memory-scope ] [--context-memory-max-chars ] ``` ## Behavior 1. load and validate config, 2. plan tasks from groups and buckets, 3. skip tasks already in `.hyperlocalise.lock.json`, 4. execute remaining tasks, 5. persist successful tasks to lock state. For lockfile fields, lifecycle, and reset guidance, see [Lockfile contract](/cli/reference/lockfile-contract). ## Supported local file formats `run` can read source and target files with these extensions: * `.json` * `.jsonc` * `.yaml` and `.yml` * `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts` * `.arb` * `.xlf`, `.xlif`, and `.xliff` * `.po` * `.html` * `.liquid` * `.md` * `.mdx` * `.strings` * `.stringsdict` * `.xcstrings` * `.csv` * `.php` * `.ftl` * Android XML `strings.xml` files at `**/res/values*/strings.xml` * `.xml` and `.resx` for generic XML locale files * `.properties` * `.srt` and `.vtt` For JSON (`.json`), `run` supports: * standard nested key/value JSON objects * FormatJS message JSON when the root strictly matches: `{"[id]": {"defaultMessage": "[message]", "description": "[description]"}}` In FormatJS mode, only `defaultMessage` is translated. Keys (message IDs), `description`, and other non-message metadata are preserved. For JavaScript and TypeScript locale modules (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`), `run` supports static locale object exports: * `export default { ... }` * `export const messages = { ... }` * `module.exports = { ... }` * `const messages = { ... }; export default messages` Nested objects are flattened to dotted keys, string arrays use bracket indexes, and strict FormatJS-style entries translate only `defaultMessage` while preserving `description` metadata. Comments, imports, export syntax, and `as const` are preserved on write. Dynamic values, computed keys, spread properties, multiple exported locale objects, and template literals with `${...}` interpolation fail with a parser error instead of being rewritten. When an existing JS/TS target module has the same key set as the source, `run` writes into the target template so translator comments and existing module layout are kept. If the source key set changes, `run` falls back to the source template to avoid merging mismatched object shapes. For YAML/YML (`.yaml`, `.yml`), `run` supports mapping-shaped locale files with string leaves. Nested mappings become dotted keys, sequences become `[index]` keys, and writeback rewrites existing string leaves while preserving key order/comments where possible. Mapping keys cannot contain `.`, `[`, or `]` because those characters are reserved for flattened paths. Non-string scalar leaves such as numbers, booleans, nulls, timestamps, anchors, and aliases are rejected to avoid silent corruption. For Flutter ARB (`.arb`), `run` translates only message keys, preserves metadata keys such as `@key`, and normalizes `@@locale` to the target locale on write. For Markdown and MDX (`.md`, `.mdx`), `run` translates extracted prose and preserves non-translatable structure: * frontmatter blocks (`---`) * fenced code blocks (` ``` ` and `~~~`) * inline code spans * Markdown anchors such as link destinations * MDX `import` and `export` lines * JSX/MDX component tags and attribute values For HTML (`.html`), `run` translates text content inside block-level elements: * `