Skip to content
Comvi

Glossary

View .md

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.
Section titled “Read next”
  • Quick start: the i18n instance, a binding and a catalog in five minutes.
  • Plugins overview: installers, plugin factories and the init() lifecycle.
  • Important defaults: the behaviours these words describe, and why each is the default.