Languages

Orbit speaks the language of the page it’s on: its buttons, the detail sheet, the media viewer, the list of the map, its messages and everything screen readers hear about the map. English and Spanish are built in. You can add any other language, change single words, or pick a language for one map.

Only Orbit’s own words change. The text of a map is the author’s, and so are the status words written in it (status: done shows as “done”). Problems Orbit reports about a map’s source (in the console, orbit validate and diagnostics) stay in English: they’re for the map’s author and their tools.

Which language a map speaks#

A map speaks the language of the element it’s drawn in: the closest lang attribute around it, through shadow roots, and then the page’s own <html lang>. A page in Spanish gets its maps in Spanish with nothing to set:

<html lang="es">
  …
  <orbit-map># Viaje
## Comida
## Lugares</orbit-map>

The language option picks a language for one map, whatever the page says:

createOrbitMap(element, markdown, { language: 'es' });

<OrbitMindMap source={markdown} language="es" />

On <orbit-map>, set its lang attribute, as on any element: <orbit-map lang="es">.

Languages are BCP 47 tags. A regional tag speaks its language with the region’s numbers and plurals: es-MX and es-ES both speak Spanish, writing 24,000 and 24.000. A language Orbit doesn’t have speaks English, and so does a map on a page that names none.

Changing the language later, with setOptions({ language }), the language prop or the element’s lang attribute, writes the map’s words again where they are.

Adding a language#

registerLanguage adds a language for every map, by its tag. Words it leaves out are English, or, for a regional tag like pt-BR, its base language’s (pt) when Orbit has it:

import { registerLanguage } from '@restless-dreams/orbit';

registerLanguage('fr', {
  focus: 'Focus',
  overview: 'Vue d’ensemble',
  zoomIn: 'Zoomer',
  zoomOut: 'Dézoomer',
  ideaCount: { one: '{count} idée', many: '{count} d’idées', other: '{count} idées' },
  // …the rest of the words in the table below.
});

It returns a function that takes the language away again. Registering a language Orbit already has changes its words for every map: registerLanguage('es', { video: 'Vídeo' }). languageTags() lists the languages maps can speak.

Placeholders, plurals and lists#

• Placeholders: words in braces ({name}, {count}) are filled in for you. Keep them in a translation, in whatever order the language needs.
• Plurals: text with a number is an object of plural forms, one for each plural category the language uses (zero, one, two, few, many) and other, which is required and covers any form left out.
• Numbers and lists: numbers are written the way the language writes them, and lists like “has note, image, and link” are joined the language’s way (“tiene nota, imagen y enlace”).

Changing single words#

The strings option changes words on one map, over its language’s:

createOrbitMap(element, markdown, { strings: { zoomIn: 'Closer', zoomOut: 'Further' } });

A word Orbit doesn’t have, or one of the wrong kind, is skipped with a warning in the console.

The root Orbit makes up#

A map that’s just a list, or has several top headings, and has no title gets a root Orbit makes up, named “Untitled map” in the map’s language. When you parse maps yourself, parseOrbit(source, { untitled: 'Mapa sin título' }) gives it that name. Its id is untitled-map in every language, so links and saved places keep working, and saving the map writes it as the list it was.

Without a browser#

renderToSVGString(markdown, { language: 'es' }) writes the drawing’s few words in a language: an untitled idea’s name, the empty map’s message and the map’s title when it has none. On the command line: orbit render map.md --language es.

Every word#

OrbitStrings in the API reference says where each one shows.