Glossary

A glossary is a curated set of terms your translations must render the same way every time. "Commit" in the version-control sense stays commit in Spanish, becomes 提交 in Simplified Chinese, and コミット in Japanese. One decision per language, enforced everywhere.

Two places a glossary can live

Glossia looks in two places for glossary entries and merges them at translation time:

• Your repository, in the files you already use for translation settings. L10N.md declares the terms, and each language's L10N/<locale>.md declares their translations. This is the developer-authoritative glossary: changes travel through pull requests, each language's reviewers own their own file, and nested files can refine it for part of the repository.
• The server, stored with your account. This is the linguist-authoritative glossary: reviewers and localization contributors add or refine entries without touching the code, through the dashboard, the REST API, or the MCP server. It applies to every repository the account translates.

Both places are useful, and neither replaces the other.

When to use which

Define a term on the server when:

• It applies to more than one repository. Product names, brand terms, and company vocabulary are defined once and used everywhere.
• The people deciding it do not work in the repository. Linguists, reviewers, and external contributors can refine the glossary even when the repository is closed source or they have no write access to it.
• You want to fix a term without a code change. A corrected translation applies on the next run, with no pull request against the codebase.
• Changes need review and history. Every edit creates a new version with a change note, contributors can propose changes as suggestions for someone to approve, and earlier versions stay available.
• Other tools need it. Agents and integrations can read the glossary through the REST API and the MCP server, for example to write new content that already uses the approved terms.

Define a term in your repository when:

• It belongs to this codebase. A term whose meaning is specific to one project, such as "commit" meaning the version-control action, sits next to the code that uses it.
• It should change together with the source text. The term and the copy that introduced it land in the same pull request and are reviewed together.
• Only part of the repository needs it. A nested L10N.md or L10N/<locale>.md can add or override entries for one directory, such as marketing pages.
• It must override the server. A repository entry wins over a server entry for the same term, for the languages it translates.

How they combine

For each file and target language, Glossia resolves the two glossaries into one effective set:

1. Start with the server glossary entries for the target language.
2. Overlay the repository entries for that language: the terms from the file's L10N.md chain that have a translation in its L10N/<locale>.md chain. When a repository entry has the same source term as a server entry, the repository entry wins.
3. If a repository term has no translation for a language, the server entry for that language still applies. The repository never blocks a language it did not translate.

The merge happens per target language, not per entry. A Spanish translation of "commit" in L10N/es.md replaces the server's Spanish entry for "commit", but does not touch the server's Japanese entry for the same term. Reviewers can see which server entries were replaced: the translation session summary shows how many were overridden, and each file's lockfile lists them under glossary.shadowed.

When the glossary changes, files re-translate

When you edit a glossary entry, Glossia only re-translates the files whose effective glossary changed. If a file's source text contains no matches for the edited term, its translations stay untouched. If a file uses the term, its next translation pass includes the updated instruction.

The same principle applies in reverse: adding a term used only by a subset of files does not force a full re-run.

What a glossary is not

• Not a machine-translation dictionary. Glossia's model reads the surrounding context and can render a term differently if the sentence demands it. The glossary is guidance, not substitution.
• Not the whole style guide. Voice, tone, formality, and audience live in your account's Voice configuration and in L10N.md. The glossary is only for individual terms and their approved translations.
• Not silent. Every applied term is recorded in the file's lockfile so a reviewer can trace exactly which glossary entries reached the model.

Related

• Add your first terms: Define a glossary.
• Every entry field: Glossary reference.
• The other L10N.md fields: L10N.md reference.