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.
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
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().
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.
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>