# Glossary

The words the Comvi i18n docs use, one sentence each, and the synonyms they avoid: i18n instance, binding, catalog, namespace, locale, compiler, installer, loader, capability, Content Deploy.

Canonical: https://comvi.io/docs/i18n/glossary

Each term is the one word the docs use for one thing. Where a synonym is common elsewhere, the
entry names it so you can map it.

## Objects

- **i18n instance**: the object `createI18n()` returns, holding the catalog, the current locale and `t()`; its type is `I18n`, and `WrapperI18nInstance` is the surface every binding requires of it. Say *the i18n instance* (or *the instance* once the page has named it), not `host`, *i18n object* or *client*.
- **Binding**: the framework package, `@comvi/react`, `@comvi/vue`, `@comvi/svelte`, `@comvi/solid`, `@comvi/next` or `@comvi/nuxt`, that hands the instance to components through a provider and `useI18n()` and turns its events into the framework's reactivity. Say *binding*, not *adapter*, *integration* or *wrapper*; the `@comvi/vue` wrapper is the one object the docs call a wrapper.
- **`t()`**: the translation function that takes a key and parameters and returns a string for the current locale. Say *`t()`*, not *the translate function* or *the translator*; a translator is a person.

## Content

- **Catalog**: the key-to-message object for one locale and one namespace, nested or flat, that the instance flattens on ingestion. Say *catalog*, not *translation file*, *locale file*, *resource* or *messages file*.
- **Message**: one value in a catalog, the text `t()` renders for a key, with its `{param}` placeholders and ICU arguments. Say *message*, not *string*, *translation* (that is the whole activity) or *copy*.
- **Messages**: the catalogs keyed by locale, or `locale:namespace`, as the `messages` option and `addMessages()` take them; `getMessages()`, `clearMessages()` and `reloadMessages()` address the same catalogs by `(locale?, namespace?)` arguments; a **translation** is the string `t()` returns for one key, as in `hasTranslation(key)` and `TranslationValue`.
- **Key**: the dot path that names one message, such as `user.profile.title`. Say *key*, not *translation id*, *string id* or *label*.
- **Namespace**: a named slice of the catalog that loads on its own, addressed as `locale:namespace` in loader maps and `messages` and as `{ ns }` in a `t()` call. The **default namespace** is `defaultNs`, `'default'` unless set; say *namespace*, not *bundle*, *group* or *scope*.
- **Active namespaces**: the set of namespaces the loader fetches for the current locale, filled by `ns`, `addActiveNamespace()` and `addMessages()`, and the list a locale switch loads. Say *active*, not *loaded*, *registered* or *enabled*; a cached namespace can be inactive and an active one can still be loading.

## Locales

- **Locale**: the value the instance is configured with and switches, such as `locale: 'de'`. Say *locale* in every SDK sentence, not *language*, *lang* or *culture*.
- **Locale code**: the canonical BCP-47 string a locale is written as, with a hyphen and case, such as `pt-BR` or `zh-Hant-TW`. Say *locale code*, not *language code*, *ISO code* or *tag*.
- **Language**: the platform's word for a locale on its **Languages** page, and the natural-language sense in prose such as "a right-to-left language". Use it for platform UI and for people; the instance and its options always say *locale*.
- **Fallback locale**: `fallbackLocale`, a locale or ordered list of locales tried when a key is missing in the current one. The list is the **fallback chain**; say *chain*, not *cascade* or *hierarchy*.

## Composition

- **Compiler**: the function that turns a message into a render step; the **default compiler** handles text and `{param}`, and `compiler: icuCompiler` adds `plural`, `select` and `selectordinal`. Say *compiler*, not *parser*, *formatter* or *ICU mode*.
- **Installer**: a function that takes the instance and returns the instance, composed with `.use(installer)` before `init()`. `.use()` is the one composition verb; say *compose*, not *install*, *register* (that is the plugin queue) or *enable*.
- **Capability**: a group of instance members an installer adds, such as the loader (`attachLoader`, `loader(map)`), plugins (`plugins()`) and devtools (`devtools()`). A capability that is not composed is *absent*, not *disabled*; say *compose a capability*, not *turn on a feature*.
- **Plugin**: a function of the instance that runs during `init()` and may return a cleanup function, queued with `registerPlugin()` or wrapped in `definePlugin()` for `.use()`. Say *plugin* for the function and *installer* for what goes in `.use()`; a *raw plugin* is a plugin handed to `.use()` by mistake.
- **Two names for one plugin**: each plugin package exports an installer for `.use()` and a `Plugin`-suffixed factory for `registerPlugin()`, such as `cdnLoader()` and `cdnLoaderPlugin()`. Say *installer* and *plugin factory*, not *plugin class* or *the CdnLoader*.
- **Loader**: the capability that fetches a catalog for a `(locale, namespace)` pair on demand, from an import map, a function or the CDN. Say *loader*, not *backend*, *resolver*, *fetcher* or *provider*.
- **Revision events**: the events after which `t()` may return something new, `localeChanged`, `namespaceLoaded`, `loadingStateChanged`, `initialized`, `messagesCleared`, `defaultNamespaceChanged` and `configChanged`; a binding subscribes to all of them. Say *revision events*, not *change events* or *updates*.

## Rendering

- **First paint**: the first render a user sees, before any catalog has arrived from a loader. Say *first paint*, not *initial render* or *mount*.
- **Gate**: what holds children back until the catalog is in: the `fallback` prop in React and Solid, `isInitializing` in Vue and Svelte. Say *gate* and *fallback*, not *loading screen*, *suspense* or *placeholder*.
- **Hydration**: the client taking over server-rendered HTML; a **hydration mismatch** is server and client rendering different text, as when `@comvi/core/tags` is imported in one bundle only. Say *hydration*, not *rehydration* or *bootstrapping*.
- **In-context editor**: `@comvi/plugin-in-context-editor`, which lets a translator hold Alt and click rendered text to edit it on the platform. Say *in-context editor*, not *visual editor*, *live editor* or *WYSIWYG*.

## Platform

- **Content Deploy**: the setting under **Settings → Content Deploy** in a Comvi project that publishes ticked locales to the CDN. Say *Content Deploy*, not *Distributions*, *publishing* or *release*.
- **CDN endpoint**: the URL Content Deploy shows, `https://cdn.comvi.io/<project-token>`, passed to `cdnLoader()` as `cdnUrl`. Say *CDN endpoint* or *`cdnUrl`*, not *CDN link*, *bundle URL* or *an env var*.
- **Project token**: the identifier at the end of the CDN endpoint that names the project to the CDN. Say *project token*, not *project id*, *API key* (which is a secret for the API) or *slug*.

## Tooling

- **Typegen**: `comvi typegen` from `@comvi/cli`, or `@comvi/vite-plugin`, writing a `.d.ts` that augments the **`TranslationKeys`** interface so `t()` autocompletes keys and checks parameters. Say *typegen* and *generated keys*, not *codegen*, *type generation* or *typed i18n*.

## Read next

- [Quick start](/docs/i18n/quick-start): the i18n instance, a binding and a catalog in five minutes.
- [Plugins overview](/docs/i18n/plugins): installers, plugin factories and the `init()` lifecycle.
- [Important defaults](/docs/i18n/important-defaults): the behaviours these words describe, and why each is the default.