Skip to main content

Class: default

Defined in: src/lib/i18n/index.ts:208

The text the UI shows, in the chosen language. Starts in the fallback locale; useDeviceLocale switches to the best match for the device, and setLocale to any available locale. Locale files load when first used, without reloading the page. Strings missing from a locale come from the fallback locale, then the key itself.

Other projects can add their own strings and locales with addLocales and addStrings. A locale's strings from every set load together and are merged in the order the sets were added (PaintCanvas's first), so a key in a later set replaces the same key in an earlier one. Keys are prefixed by project by convention: paintCanvas. for PaintCanvas's, and e.g. liveCanvas. for an app's.

Dispatches a change event when the locale or its strings change, so the UI can show the new text.

Example​

const translations = new Translations({ locales: { "en-US": ..., ja: () => import("./ja.json") } });
await translations.useDeviceLocale();
translations.t("paintCanvas.layers.delete", { name: "Sketch" });

Extends​

  • EventTarget

Constructors​

Constructor​

new default(options?): Translations

Defined in: src/lib/i18n/index.ts:222

Parameters​

options?​

TranslationsOptions = {}

Returns​

Translations

Overrides​

EventTarget.constructor

Accessors​

locale​

Get Signature​

get locale(): string

Defined in: src/lib/i18n/index.ts:233

The locale in use (an IETF BCP 47 tag, e.g. ja)

Returns​

string


locales​

Get Signature​

get locales(): string[]

Defined in: src/lib/i18n/index.ts:238

Locales that can be used: the fallback, and every locale a set of strings can load

Returns​

string[]

Methods​

addEventListener()​

addEventListener(type, callback, options?): void

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14380

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Parameters​

type​

string

callback​

EventListenerOrEventListenerObject | null

options?​

boolean | AddEventListenerOptions

Returns​

void

Inherited from​

EventTarget.addEventListener


addLocales()​

addLocales(loaders): Promise<void>

Defined in: src/lib/i18n/index.ts:287

Add a set of strings for some locales, loaded when first used, after the sets already added (so its keys replace theirs). Its locales become available. The locale in use and the fallback load straight away, then change is dispatched if the set has strings for either.

Parameters​

loaders​

Record<string, LocaleLoader>

Returns​

Promise<void>

Example​

await translations.addLocales({
"en-US": () => import("./locales/en-US.json"),
fr: () => import("./locales/fr.json"),
});
translations.t("liveCanvas.share");

addStrings()​

addStrings(locale, strings): void

Defined in: src/lib/i18n/index.ts:302

Add or replace strings for a locale (e.g. the implementer's own wording or extra keys), after the sets already added. Dispatches change if it's the locale in use or the fallback.

Parameters​

locale​

string

strings​

Strings

Returns​

void

Example​

translations.addStrings("en-US", { "paintCanvas.tool.brush": "Paintbrush" });

dispatchEvent()​

dispatchEvent(event): boolean

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14386

The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent().

MDN Reference

Parameters​

event​

Event

Returns​

boolean

Inherited from​

EventTarget.dispatchEvent


removeEventListener()​

removeEventListener(type, callback, options?): void

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14392

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

MDN Reference

Parameters​

type​

string

callback​

EventListenerOrEventListenerObject | null

options?​

boolean | EventListenerOptions

Returns​

void

Inherited from​

EventTarget.removeEventListener


setLocale()​

setLocale(tag): Promise<void>

Defined in: src/lib/i18n/index.ts:265

Switch to a locale (the best available match for the tag), loading its strings from every set if needed. Dispatches change once they're ready. If loading fails, the current locale stays and this rejects.

Parameters​

tag​

string

Returns​

Promise<void>

Example​

await translations.setLocale("zh-TW"); // uses zh-Hant

t()​

t(key, values?): string

Defined in: src/lib/i18n/index.ts:344

Translate a key, putting values into its {name} placeholders. With a numeric count, the key's plural form for the locale is used when there is one (e.g. paintCanvas.presets.imported.one and paintCanvas.presets.imported.other). Falls back to the fallback locale, then the key.

Parameters​

key​

string

values?​

Record<string, string | number>

Returns​

string

Example​

translations.t("paintCanvas.presets.imported", { count: 3 }); // "Imported 3 brush presets"

useDeviceLocale()​

useDeviceLocale(languages?): Promise<void>

Defined in: src/lib/i18n/index.ts:250

Switch to the best available locale for the device's languages (navigator.languages).

Parameters​

languages?​

readonly string[] = ...

Returns​

Promise<void>