Configuration

Polyglot is configured via a polyglot.toml file in your project root. Run polyglot init to generate one.

Keep your existing app configuration

Run commands from the app root. In a monorepo, doctor --apps helps choose it; framework discovery at the repository root is not enough. doctor reports the actual runtime, catalog loader, locale strategy and uncertainties before a plan is prepared.

init --local creates local configuration without hosted linking. Re-running init merges explicitly selected choices and preserves customized settings, project binding and comments. --yes removes prompts; it is not a blanket reset. Inspect the diff after an intentional change and replan if inputs changed.

polyglot doctor --apps
polyglot init --local
polyglot doctor
polyglot init --languages fr,de --yes --local

Full reference

[project]
name = "my-app"                         # Project name
framework = "nextjs"                    # nextjs, astro, sveltekit, reactnative, flutter, vue, angular
source_language = "en"                  # Source language code
target_languages = ["es", "fr", "de"]   # Target language codes
project_id = "..."                      # Added after hosted linking; non-secret, safe to commit
repository = "github.com/acme/my-app"   # Auto-added: git remote that maps the repo to one project per workspace

[detection]
include_paths = ["src"]                 # Directories to scan (default: framework-specific)
exclude_paths = ["src/generated"]       # Directories to skip
translatable_attributes = ["alt"]       # Extra HTML attributes to detect

[detection.rules]
ignore_strings = ["TODO"]               # Exact strings to skip
ignore_patterns = ["^[A-Z_]+$"]         # Regex patterns to skip
ignore_element_types = ["Script"]       # AST node types to skip
ignore_files = ["src/test/**"]          # File glob patterns to skip
additional_attributes = ["data-label"]  # Extra attributes to detect
translation_functions = ["t", "i18n"]   # Functions that indicate already-translated strings
additional_property_keys = ["badge"]    # Extra object keys to treat as translatable
ignore_property_keys = ["name"]         # Object keys to always skip

[translation]
api_url = "https://api.getpolyglot.ai"  # API endpoint (override for self-hosted)
output_dir = "public/locales"            # Where to write translation files
output_format = "json"                   # json | yaml | arb | strings | xml
coverage_threshold = 100.0               # Min coverage % for CI checks
key_style = "nested"                     # nested | flat | semantic
library = "next-intl"                    # React adapter override; usually auto-detected
rich_text = true                         # Keep supported complete rich messages

[translation.contexts]
"file.open" = "Button that opens a document"
"store.open" = "Status indicating the shop is currently open"

Note: your API key is not stored in polyglot.toml. It lives in your local credentials (from polyglot auth login) or the POLYGLOT_API_KEY environment variable for CI. The file only holds the non-secret project_id binding, so it's safe to commit and share with your team.

Project

Detection

All detection settings are optional. Polyglot uses sensible defaults based on your framework.

Custom rules

Fine-tune detection behavior under [detection.rules].

Handling false positives

Polyglot's detection is intentionally broad — it's better to flag a questionable string than miss a real one. If you see strings that shouldn't be translated, you have several options:

[detection.rules]
# Skip specific strings
ignore_strings = ["•", "ADMIN", "URL"]

# Skip patterns (regex)
ignore_patterns = ["^[A-Z_]+$"]   # all-caps constants

# Skip entire files
ignore_files = ["src/constants/**"]

Polyglot also detects strings inside data objects (arrays of features, pricing plans, etc.) and marks them as [data] in scan output. Unrecognized property keys in those objects appear as [hint] — you can promote them to detected strings by adding the key to additional_property_keys.

Translation

Catalog layout and adapter choices

The example output_dir is illustrative. Preserve your existing source/target catalog paths, namespaces and loader rather than moving them to match a default. Recognized next-intl request loaders can resolve custom directories such as src/messages. Discovery of a loader is not proof that every translate/push layout is supported.

library selects the React code-generation adapter where supported; it does not install or qualify arbitrary runtime wiring. rich_text defaults to true. Turning it off can fragment complete messages, so review the resulting sentence semantics. See Framework profiles for the runtime-specific contract.

Give ambiguous messages stable meaning

Use translation.contexts to distinguish identical source values such as Open. Each description applies to a catalog key, is trimmed and is limited to 2,000 characters. Explain UI meaning, audience and constraints; keep secrets and unrelated project content out of it.

Changing source text or meaning makes translations pending again. Moving components with stable keys does not reassign approvals. Removing context also changes identity. Existing approvals without context provenance are not silently reused as approvals for a new meaning.

For a namespace-qualified key use common:save; an unqualified save supplies a shared default. Catalog sync supports namespaced publication, while translate and push still need a supported readable source layout. The CLI checks that the service supports context identity before sending those requests.

[translation.contexts]
"file.open" = "Button that opens a document"
"store.open" = "Status indicating the shop is currently open"
"common:save" = "Save changes to the current document"

Environment variables

Framework and runtime profiles · Meaning, incremental work and approvals