globetrotter

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

Globetrotter is a code generator for applications that share translations across languages or frameworks. It reads TOML catalogs, validates the translations as one set, and writes:

one JSON file for each spoken language, intended for runtime loading;
TypeScript definitions for the translation structure;
Rust types for translation keys and their declared arguments.

The translation text and the type information come from the same source files. A key cannot change in one output without changing in all of them.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Globetrotter is distributed as the globetrotter command-line binary.

Homebrew#

brew install --cask LuupSystems/tap/globetrotter

The tap installs a prebuilt release. Upgrade it with the normal Homebrew workflow:

brew upgrade --cask globetrotter

From crates.io#

The binary is published by the globetrotter-cli crate:

cargo install --locked globetrotter-cli

--locked uses the dependency versions recorded for the published release.

Prebuilt releases#

Release archives for supported platforms are attached to the GitHub releases. Extract the archive and put the globetrotter executable on your PATH.

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

This example generates runtime translations for English, German, and French, plus TypeScript and Rust bindings. Every file shown here belongs to the runnable fixture under docs/examples/quickstart.

1. Write the catalog#

Create translations.toml:

translations.toml

[account.greeting]
en = "Welcome back, {{name}}!"
de = "Willkommen zurück, {{name}}!"
fr = "Bon retour, {{name}} !"
arguments = { name = "string" }

[cart.summary]
en = "You have {{count}} items in your cart."
de = "Du hast {{count}} Artikel in deinem Warenkorb."
fr = "Vous avez {{count}} articles dans votre panier."
arguments = { count = "number" }

[navigation.sign_out]
en = "Sign out"
de = "Abmelden"
fr = "Se déconnecter"

The table path is the translation key. Language fields hold the text, and arguments declares the placeholders accepted by the Handlebars template.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Globetrotter uses a versioned YAML file. By default it looks for globetrotter.yaml in the current directory; pass --config (-c) to name a file or a directory to search.

globetrotter.yaml

version: 1
configs:
 app:
 languages: [en, de, fr]
 engine: handlebars
 strict: true
 check_templates: true
 inputs:
 - path: ./translations.toml
 prefix: app
 outputs:
 json:
 - ./generated/translations_{{language}}.json
 typescript:
 type: ./generated/translations.ts
 rust:
 - ./generated/translations.rs

Paths and glob patterns are resolved relative to the config file, not the shell’s working directory. That makes a checked-in config safe to invoke from a repository root, a nested build script, or CI.

Translation files

Mon, 01 Jan 0001 00:00:00 +0000

Translation files#

Translation sources are TOML. Each table path is a translation key; its fields are spoken-language codes and, optionally, an argument declaration.

translations.toml

[account.greeting]
en = "Welcome back, {{name}}!"
de = "Willkommen zurück, {{name}}!"
fr = "Bon retour, {{name}} !"
arguments = { name = "string" }

[cart.summary]
en = "You have {{count}} items in your cart."
de = "Du hast {{count}} Artikel in deinem Warenkorb."
fr = "Vous avez {{count}} articles dans votre panier."
arguments = { count = "number" }

[navigation.sign_out]
en = "Sign out"
de = "Abmelden"
fr = "Se déconnecter"

Keys#

Nested TOML tables become dotted keys. This table:

Generated outputs

Mon, 01 Jan 0001 00:00:00 +0000

Generated outputs#

One run can write runtime JSON and compile-time bindings. All examples on this page are generated from the checked-in quick-start catalog before the documentation site is built.

Runtime JSON#

Globetrotter writes one versioned JSON document per language. Its translations object maps fully qualified keys to literal text or templates:

translations_en.jsongenerated

{
 "version": "1",
 "template_engine": "handlebars",
 "language": "en",
 "translations": {
 "app.account.greeting": {
 "template": "Welcome back, {{name}}!"
 },
 "app.cart.summary": {
 "template": "You have {{count}} items in your cart."
 },
 "app.navigation.sign_out": {
 "literal": "Sign out"
 }
 }
}

The key set is shared across language files, so an application can choose a file at runtime without changing the lookup contract. Values without arguments remain literals; values with Handlebars placeholders remain templates for the application to render.

Linting

Mon, 01 Jan 0001 00:00:00 +0000

Linting#

globetrotter lint validates translation sources without writing generated files:

$ globetrotter lint
 
 
 INFO globetrotter::lint: no issues found in 0ms

The deterministic checks report:

a missing required language;
empty text or leading/trailing whitespace;
a template that does not compile with the configured engine;
a value substituted in some languages but not in others; a name that only selects a wording, such as {{#if my_condition}}, may be absent from a language without that distinction;
a condition whose branches are identical, so it has no effect;
placeholders that are undeclared, or arguments that are never used;
identical translations within one key;
duplicate text shared by different keys.

The template checks use the configured engine (or --engine) and are never run with a guessed one: without an engine, or with one that has no template analysis yet, they are skipped and a note says so. Handlebars is the only engine with template analysis today.

CLI reference

Mon, 01 Jan 0001 00:00:00 +0000

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:

Continuous integration

Mon, 01 Jan 0001 00:00:00 +0000

Continuous integration#

A translation pipeline normally has three independent gates:

source files are formatted;
source files pass lint;
committed generated files match the current catalogs and generator.

Keep those checks separate enough that a failure says what changed.

Verify committed output#

When generated files are committed, regenerate them and fail on a diff:

globetrotter format --check
globetrotter lint
globetrotter
git diff --exit-code -- generated/

Replace generated/ with the output paths from your config. Running generation before git diff tests the same config developers use locally; it does not rely on a second list of expected keys.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ#

Does Globetrotter render translations at runtime?#

No. It generates JSON data and language bindings. Your application loads the appropriate JSON file and renders templates with its own Handlebars-compatible runtime or another integration.

Why are languages fields in the same TOML table?#

Keeping a key’s translations together makes missing languages and placeholder differences visible to both reviewers and the linter. Output is still split by language for runtime loading.

Must generated files be committed?#

No. Commit them when consumers need to build without the generator; otherwise generate them as part of the build. In either case, establish one owner for the files and never edit them manually.