GLOSSIA.md

GLOSSIA.md tells Glossia which files to translate, where translated files belong, which languages to target, and what context should guide the result. A repository can have a root file and additional scoped files in subdirectories.

Structure

Each file has two parts:

1. YAML Ain't Markup Language frontmatter between --- markers.
2. Markdown below the frontmatter with product, audience, voice, or domain context.

---
source_language: en
model: translation-default
sources:
  "docs/**/*.md": "docs/i18n/{locale}/{relpath}"
targets:
  - es
  - ja
validation:
  - ./scripts/validate-docs.sh
  - --strict
frontmatter: preserve
preserve:
  - placeholders
  - urls
---

Write for software developers. Keep product names and code samples unchanged.

Provider credentials belong in account settings, never in GLOSSIA.md. The optional model value is an account model handle.

Frontmatter fields

Field	Type	Required	Description
source_language	string	no	Source locale for this scope. Defaults to en.
model	string	no	Account model handle. Glossia uses the account default when omitted and reports an error when an explicit handle does not exist.
sources	map or list	for a top-level rule	Source file patterns. Map values can define output templates.
targets	map or list	when sources are configured	Target locale codes. A map can associate a locale code with a language name.
output	string	when no source mapping or target_path supplies a destination	Output file template.
target_path	string	when no source mapping or output supplies a destination	Base directory template for translated files.
translate	list	no	Multiple translation rules, each with its own sources and optional overrides.
exclude	list	no	File patterns to skip.
preserve	list	no	Content kinds that must remain unchanged, such as placeholders or uniform resource locators.
frontmatter	string	no	preserve by default, or translate.
prompt	string	no	Additional guidance for this scope or rule.
validation	list	for file extensions without a built-in adapter	A validation command followed by its arguments. The command receives the candidate at its real target path and must return a nonzero status when the file is invalid.
check_cmd	string	no	A check command available to the translation workflow.
check_cmds	map	no	Named check commands available to the translation workflow.
retries	integer	no	Number of retry attempts after a failed check. Defaults to 2.
locale	string	no	Locale attached to a locale-specific context file.

Unknown frontmatter fields are ignored.

File formats

Glossia has built-in handling for Markdown, JavaScript Object Notation, YAML Ain't Markup Language, portable object, and plain text files. Other file extensions fail planning unless the applicable GLOSSIA.md declares a validation command. This avoids silently treating a proprietary structured format as unconstrained text.

The validation command runs after the candidate has been written temporarily to its real target path. It can invoke the repository's native parser, compiler, or build command. Glossia restores the previous target after each validation attempt and only writes the accepted candidate afterward.

Source mappings

The clearest form maps every source pattern to an output template:

sources:
  "docs/**/*.md": "docs/i18n/{locale}/{relpath}"
  "content/*.json": "content/{locale}/{basename}.{ext}"

A source list is also valid, but it needs output or target_path to define the destination:

sources:
  - "docs/**/*.md"
target_path: "docs/i18n/{locale}"

Target languages

A list uses each locale code as its language identifier:

targets:
  - es
  - ja

A map can add a readable language name:

targets:
  es: Spanish
  ja: Japanese

Output variables

Variable	Value
{locale} or {lang}	Target locale code.
{relpath}	Source path relative to the matched pattern.
{basename}	Source filename without its extension.
{ext}	Source file extension without the leading dot.

Multiple rules

Use translate when different content groups need different destinations or checks:

---
source_language: en
targets:
  - es
translate:
  - sources:
      - "docs/**/*.md"
    output: "docs/i18n/{locale}/{relpath}"
  - source: "messages/*.json"
    output: "messages/{locale}/{basename}.{ext}"
---

Rule values override values inherited from the surrounding file.

Scoped context

Glossia reads GLOSSIA.md files from the repository root toward the source file:

• Parent settings provide defaults.
• A deeper file overrides fields for its directory.
• Markdown context is accumulated from parent to child.
• Locale-specific guidance and a locale-specific model handle can live in GLOSSIA/<locale>.md.

This lets a repository keep broad voice guidance at the root while placing product-area or language-specific guidance close to the content it affects.