Reference · glosa

Entries

Entry	What it has
`glosa/vite`	`glosa()`, the Vite plugin, and `virtual:glosa`.
`glosa/vue`	`glosaVue()` and `createGlosa()`.
`glosa/react`	`GlosaProvider`, `createGlosa()`, `useGlosa()` and `GlosaT`.
`glosa/svelte`	`setGlosa()`, `getGlosa()`, `createGlosa()` and `GlosaT`.
`glosa/x18n`	The x18n plugin, as the default export, with `glosaSyntax` and `glosaScanner`.
`glosa/markdown`	`toMarkdown()`, `fromMarkdown()`, `prepare()` and `glosaSyntax`.
`glosa`	The extraction, the message format and the catalog helpers, for tools.

`glosa(options?)`

Section titled "glosa(options?)"

From glosa/vite.

Option	Default	What it does
`sourceLocale`	`"en"`	The language the components are written in.
`dir`	`"locales"`	The catalog folder, from the Vite root.

virtual:glosa exports { sourceLocale, catalogs } as its default: the source locale and a loader for each <dir>/<locale>.json. Pass it to createGlosa.

`createGlosa(options?)`

Section titled "createGlosa(options?)"

From glosa/vue, glosa/react, glosa/svelte or glosa. Returns a store. Make one per app, and one per request on the server.

Option	Default	What it does
`sourceLocale`	`"en"`	The language the components are written in.
`locale`	The source locale	The first locale. Its catalog starts loading at once; await `ready`.
`catalogs`	none	Catalog loaders by path, as `import.meta.glob` returns them.
`messages`	none	Catalogs already loaded, by locale.

The store:

Member	What it does
`locale`	The current locale.
`sourceLocale`	The source locale.
`locales`	Every locale with a catalog, the source locale first.
`ready`	Settles once the first locale's catalog is loaded.
`setLocale(locale)`	Loads the locale's catalog if needed, then switches. Throws for a locale with no catalog.
`t(id, source, args?)`	The message in the current locale, with its placeholders filled in.
`tree(id, source)`	The message as a tree, for one with tags.
`update(locale, catalog)`	Replaces a locale's catalog, as a live update does.
`subscribe(listener)`	Calls `listener` after the locale or its catalog changes. Returns the unsubscribe function.

The rewritten components call t and tree; you rarely need them yourself.

Vue

Section titled "Vue"

glosaVue(glosa) is a plugin for app.use. It registers the $glosa function and the <GlosaT> component, which the rewritten templates use, and provides the store as "glosa", so inject<Glosa>("glosa") returns it.

React

Section titled "React"

<GlosaProvider glosa={glosa}> gives the store to its tree. useGlosa() returns the current locale's t, as the rewritten components use it for attributes. <GlosaT> renders a message with its tags. Without a provider, they use one store for the whole module, which is fine in a single-page app and wrong on a server.

Svelte

Section titled "Svelte"

setGlosa(glosa) makes the store the one of the calling component and its descendants, and returns it. Call it in the root component. getGlosa() returns a Svelte store of the current locale's t, which the rewritten components read. GlosaT renders a message with its tags.

`glosa/x18n`

Section titled "glosa/x18n"

The default export, glosa(options?), takes the same sourceLocale and dir as the Vite plugin. It tells x18n the catalogs are flat files at <dir>/{locale}.json, adds glosa's placeholder syntax, and adds a scanner that finds each message in .vue, .jsx, .tsx and .svelte files.

`glosa/markdown`

Section titled "glosa/markdown"

Export	What it does
`prepare(id, text, glosaSyntax)`	Splits a message into the parts a translator sees.
`toMarkdown(messages)`	One Markdown document for a list of prepared messages.
`fromMarkdown(messages, markdown, options)`	Reads a translated document back. `options` takes `locale` and `basis`, the export it was made from.

`glosa`

Section titled "glosa"

For tools built on glosa: extract(code, filename) returns a file's messages and its rewritten code, EXTENSIONS the file types it reads, and hashOf(text) a message's ID. tokenize, toTree, problem and hasMarker read the message format, and collect, match and writeCatalogs write the catalogs as the Vite plugin does.

The message format

Section titled "The message format"

Marker	Stands for
`{name}`	An expression, named after its last property: `user.name` is `{name}`.
`{0}`	Any other expression, numbered in order.
`<0>…</0>`	An inline element that wraps text, numbered in order.
`<0/>`	An element the translator moves but doesn't edit: `br`, `img`, `code`, a component with no children, anything with `translate="no"`.

A translation keeps every marker of its source and may reorder them. Its tags must nest. A translation that breaks either rule isn't shown; the source text is.

A message's ID is the first ten hex characters of the SHA-256 of its source text.