CLI reference#

Running globetrotter without a subcommand generates every configured output. The format and lint subcommands operate on the same discovered inputs.

$ globetrotter --help
 
Polyglot, type-safe internationalization
 
Usage: globetrotter [OPTIONS] [COMMAND]
 
Commands:
  format  Formats translation files in place
  lint    Lints translation files and reports any issues
  help    Print this message or the help of the given subcommand(s)
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --check[=<CHECK_TEMPLATES>]
          Whether to validate that all templates render successfully
 
          [possible values: true, false]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Generation#

globetrotter [OPTIONS]

Common options:

Option	Purpose
`-c, --config <PATH>`	Load a config file, or search a directory for one. Repeatable.
`-i, --translation <PATH>`	Add a translation file directly. Repeatable.
`--engine <ENGINE>`	Override the configured template engine.
`--strict[=<BOOL>]`	Promote warnings to errors.
`--check[=<BOOL>]`	Compile and validate templates.
`--dry-run[=<BOOL>]`	Run without writing output files.
`--absolute[=<BOOL>]`	Print absolute paths instead of paths relative to the shared base directory.
`--max-keys <N>`	Process a bounded prefix of each config for debugging.
`--color <CHOICE>`	Control ANSI color output.
`--log <LEVEL>`	Set the log level unless `RUST_LOG` overrides it.
`--log-format <FORMAT>`	Select pretty or JSON logs.

When neither --config nor --translation is present, Globetrotter searches the current directory for its config file.

Format#

globetrotter format [OPTIONS]

The formatter sorts translation keys while preserving comments. It defaults to ascending order. --check exits non-zero when a file would change and is suitable for CI.

$ globetrotter format --help
 
Formats translation files in place
 
Usage: globetrotter format [OPTIONS]
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --order <ORDER>
          Order in which translation keys are sorted
 
          Possible values:
          - ascending:  Sort keys from A to Z
          - descending: Sort keys from Z to A
 
          [default: ascending]
 
      --check
          Check whether files are already formatted instead of rewriting them.
 
          Exits with a non-zero status if any file would be reformatted.
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Lint#

globetrotter lint [OPTIONS]

Lint includes all shared input and config options. Its own controls cover source-usage scanning, duplicate detection, and the experimental LLM judge.

$ globetrotter lint --help
 
Lints translation files and reports any issues
 
Usage: globetrotter lint [OPTIONS]
 
Options:
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten.
 
          [env: LOG_LEVEL=]
 
      --usages <DIR>
          Report translation keys never referenced in this source directory.
 
          Repeatable. When omitted, the unused-key check is skipped.
 
      --log-format <LOG_FORMAT>
          log format (json, pretty, or pretty-compact)
 
          [env: LOG_FORMAT=]
 
      --no-duplicates
          Disable duplicate-translation detection entirely
 
      --color <COLOR_CHOICE>
          enable or disable color
 
          [env: GLOBETROTTER_COLOR=]
 
      --llm-judge
          (experimental) Asks an LLM whether each key's languages tell the user the same thing.
 
          Each key is judged in one request against an OpenAI-compatible endpoint (a local ollama by default). Findings are printed as notes with the model's reason and never fail the lint: the judge is tuned for recall, so treat every finding as a suggestion for inspection. Verdicts are cached, so re-runs only pay for changed keys.
 
          Use a capable model: in testing, 4B-class models missed real drift and hallucinated justifications, while `gemma4:12b` and `qwen3.5:9b` (Q4, 4K context) with medium reasoning effort worked well.
 
  -c, --config <CONFIG_PATHS>
          Paths to globetrotter config files or directories to search for one
 
      --llm-base-url <URL>
          Base URL of the OpenAI-compatible endpoint
 
          [default: http://localhost:11434/v1]
 
  -i, --translation <TRANSLATIONS>
          Paths to translation files to process
 
      --llm-model <MODEL>
          Model name as known to the endpoint
 
          [default: gemma4:12b]
 
      --engine <TEMPLATE_ENGINE>
          Template engine to use for rendering translations
 
      --llm-api-key-env <ENV>
          Name of the environment variable holding the API key.
 
          Local servers ignore the key, so leaving the variable unset is fine.
 
          [default: OPENAI_API_KEY]
 
      --llm-concurrency <N>
          Maximum number of concurrent requests
 
          [default: 8]
 
      --strict[=<STRICT>]
          Treat warnings as errors
 
          [possible values: true, false]
 
      --llm-temperature <T>
          Sampling temperature. The default `0` keeps verdicts reproducible (and cacheable) across runs
 
          [default: 0]
 
      --absolute[=<PRINT_ABSOLUTE_PATHS>]
          Print absolute paths instead of paths relative to the common base directory
 
          [possible values: true, false]
 
      --llm-effort <EFFORT>
          Reasoning effort, for models that support it
 
          Possible values:
          - none:   Sends no reasoning-effort field
          - low:    Minimal reasoning; fastest, least reliable
          - medium: Balanced reasoning; the tested sweet spot for drift detection
          - high:   Maximal reasoning; slowest
 
          [default: medium]
 
      --dry-run[=<DRY_RUN>]
          Run without writing any output files
 
          [possible values: true, false]
 
      --llm-min-confidence <MIN>
          Minimum confidence a finding needs to be reported.
 
          Each finding carries the model's self-reported confidence (0 to 1), which is only loosely calibrated — treat it as a ranking of findings, not a probability. The default `0` reports everything, keeping recall maximal; raise it to trade recall for fewer false positives. The threshold applies after the verdict cache, so changing it re-filters cached verdicts without new requests.
 
          [default: 0]
 
      --llm-prompt <FILE>
          File with a custom judge prompt template.
 
          The template must contain the `{key}` and `{languages}` placeholders; all other braces pass through verbatim. Prompt wording strongly affects which findings a given model reports, and the best wording differs per model, so tune the template together with `--llm-model`.
 
      --max-keys <N>
          Process only the first `N` translation keys of each config.
 
          A debugging aid for large corpora: try a change — or the LLM judge — against a small subset of real translations before paying for a full run. Applies to linting and generation alike; the truncation is warned about, never silent.
 
      --cache-dir <DIR>
          Directory for cached data (e.g. LLM judge verdicts).
 
          Defaults to a `globetrotter` folder in the OS user cache directory (e.g. `~/.cache/globetrotter` on Linux).
 
          [env: GLOBETROTTER_CACHE_DIR=]
 
      --llm-cache-capacity <N>
          Maximum number of cached verdicts kept on disk (least-recently-used eviction); `0` disables the cache entirely
 
          [default: 100000]
 
  -h, --help
          Print help (see a summary with '-h')
 
  -V, --version
          Print version

Useful groups:

--usages <DIR> is repeatable and enables unused-key scanning.
--no-duplicates disables both cross-key duplicate checks and identical-language checks.
--llm-judge enables semantic drift review.
--llm-base-url, --llm-model, and --llm-api-key-env select the endpoint.
--llm-concurrency, --llm-temperature, and --llm-effort control requests.
--llm-prompt loads a custom prompt containing {key} and {languages}.
--llm-min-confidence filters reported findings after the cache.
--cache-dir and --llm-cache-capacity control persisted verdicts.

The generated help above is captured from the working-tree binary during every documentation build, so it is the authoritative list when flags change.