Internationalization

Sync Engine merges translation resources from all modules at runtime.

Translations

Translations is a merged resource map (type only) at ctx.i18n. Core keys cover sync, module loading, settings, modals, and UI labels. Module resources registered through registerI18n merge into the translation function at runtime.

You can inspect the full core map in Sync Engine core English translations.

ObsidianLanguageCode

Union of language codes supported by Obsidian, such as 'en', 'en-GB', and 'zh'.

Fragment, TranslationResource, and Translate

type Fragment<A = undefined> = (fragment: DocumentFragment, args: A) => void;

type TranslationResource = Record<string, string | Fragment<any>>;

String resources return strings. They may accept optional interpolation objects, replacing double-curly-brackets placeholders. Fragment resources receive a DocumentFragment and optional typed arguments, then return a DocumentFragment from translate.

import type { Fragment, Translate, TranslationResource } from '@hesprs/sync-engine-sdk';

const messages = {
  connected: 'Connected to {{backend}}.',
  files: (frag: DocumentFragment, { succeeded, failed }: { succeeded: number; failed: number }) => {
    frag.createEl('p', { text: `Files synchronized:` });
    const ul = frag.createEl('ul');
    ul.createEl('li', { text: `${succeeded} files succeeded` });
    if (failed) ul.createEl('li', { text: `${failed} files failed.` });
  },
  website: (frag: DocumentFragment) => {
    frag.appendText('Visit ');
    frag.createEl('a', {
      attr: { href: 'https://sync.consensia.cc' },
      text: 'Sync Engine Website',
    });
    frag.appendText(' for more detail.');
  },
} satisfies TranslationResource;

ctx.registerI18n('en', messages);

const translate: Translate<typeof messages> = ctx.translate;
const label = translate('connected', { backend: 'Example' });
const content = translate('files', { succeeded: 3, failed: 0 });

label is a string; content is a DocumentFragment that you can append to HTML elements. Use string for simple translations, use Fragment factory for complex blocks requiring HTML construction or dynamic composition.

Obsidian DOM augmentation Element.createSpan(), Element.createEl(), Element.createDiv(), Element.appendText() are highly recommended when constructing Fragment i18n values.

Registering Translations

See registration.