i18n.config.json

i18n.config.json is the project-level configuration file. It lives in your project root and is committed to version control.

Create it with:

i18n init

---

Full example

{
  "key": "i18n_pk_your_key_here",
  "profile": "en:prod",
  "chunks": {
    "index":    ["nav.*", "common.*", "footer.*", "errors.*"],
    "checkout": ["checkout.*", "payment.*", "cart.*"],
    "account":  ["account.*", "profile.*", "settings.*"]
  },
  "scan": {
    "include": ["src/**/*.{tsx,jsx,ts,js,vue,html,erb,html.erb}"],
    "exclude": ["node_modules", "dist", ".next", "coverage", "*.test.*", "*.spec.*"]
  },
  "push": {
    "dryRun": false,
    "failOnUnknownKeys": false
  }
}

---

Field reference

key (required)

Your public API key. Starts with i18n_pk_. Found in the dashboard under Settings → API Keys.

"key": "i18n_pk_abc123xyz"

profile (required)

The default profile for CLI operations. Used by i18n push, i18n validate, i18n publish, and i18n coverage when --profile is not specified.

"profile": "en:prod"

Profile names follow the pattern {locale}:{environment}, e.g. en:prod, fr:staging, de:prod.

chunks (optional)

Defines how keys are grouped into chunk files for the CDN. Each chunk is downloaded independently by the loader script.

"chunks": {
  "index":    ["nav.*", "common.*", "footer.*"],
  "checkout": ["checkout.*", "payment.*"]
}

Key patterns use glob-style matching:

• nav.* — all keys starting with nav.
• checkout.** — all keys starting with checkout. at any depth
• form.*.label — any key matching this three-segment pattern

Keys that don't match any chunk pattern are assigned to the index chunk.

If chunks is omitted, all keys are placed in a single index chunk.

scan.include (required)

Glob patterns for files to scan for data-label attributes and i18n.t() calls.

"scan": {
  "include": ["src/**/*.{tsx,jsx,vue,html,erb}"]
}

Supports brace expansion — {tsx,jsx} matches both .tsx and .jsx files.

scan.exclude (optional)

Glob patterns to exclude from scanning. Applied after include.

"scan": {
  "include": ["src/**/*.tsx"],
  "exclude": ["**/*.test.tsx", "**/*.stories.tsx", "src/generated/**"]
}

Defaults to ["node_modules", "dist", ".next", ".nuxt", "build"].

push.dryRun (optional)

When true, i18n push previews changes without writing to ShipEasyI18n. Same as passing --dry-run on the command line.

"push": {
  "dryRun": false
}

push.failOnUnknownKeys (optional)

When true, i18n push exits with code 1 if it finds keys in the codebase that don't exist in ShipEasyI18n and aren't being created in this push. Useful as a strictness gate.

---

Multiple profiles

If you push to a non-default profile, pass --profile on the command line:

i18n push --profile en:staging
i18n validate --profile en:staging

The profile field in i18n.config.json is the default only — it doesn't restrict which profiles you can target.

---

Per-directory config

Place a i18n.config.json in a subdirectory to override settings for that directory:

project/
  i18n.config.json          # key, global scan patterns
  packages/
    checkout/
      i18n.config.json      # overrides: chunks, scan.include for this package

The CLI merges configs by walking up from the CWD. More specific configs override less specific ones. key is always read from the root config.

---

CI configuration

For CI environments, override the token with an environment variable:

export ShipEasyI18n_SECRET_TOKEN=i18n_at_your_ci_token
i18n push
i18n validate
i18n publish --profile en:prod

The key in i18n.config.json is still read from the file — only the secret token comes from the environment.