@0001-labs/design-system-1 0.0.0-stage → 0.3.0-alpha.13

package/dist/0-face/i18n.d.ts

@@ -0,0 +1,138 @@
+import type { Language } from "./languages";
+import type { LanguageRoutingOptions } from "./language-routing";
+import type { TranslationParams, TranslationTable, TranslationsFile } from "./translations-format";
+export type LanguageCode = string;
+export type TranslationData = {
+    [key: string]: string;
+};
+export type TranslationMap = Record<string, TranslationData>;
+/**
+ * How a product sets up the language module. Every field is optional: without
+ * any, the module behaves as it always has (the whole table from
+ * `./translations.json`, the languages offered are the ones in the words).
+ *
+ * Pass it to `configureI18n()` straight after importing the module, or put it
+ * on `window.DS_ONE_I18N` before the module loads.
+ */
+export type I18nOptions = {
+    /** Fetch external words at startup. Disable when the product supplies them in code. */
+    autoLoad?: boolean;
+    /**
+     * Every language the product speaks. When set, the picker offers these
+     * whether or not their words have arrived yet, which matters when a page
+     * loads only its own language (`languageFile`). Without it, the languages
+     * offered are the ones found in the loaded words.
+     */
+    languages?: readonly LanguageCode[];
+    /**
+     * Where one language's words are published, so a page loads its own
+     * language rather than the whole table: a pattern with `{language}` in it
+     * (`"/translations/{language}.json"`) or a function. Each file holds
+     * `{ "<language>": { …words } }`. When a language's file is missing, the
+     * whole table is the fallback. Without it, only the whole table is loaded.
+     */
+    languageFile?: string | ((language: LanguageCode) => string) | null;
+    /**
+     * Where the whole table is published. Defaults to `./translations.json`.
+     * `window.DS_ONE_TRANSLATIONS_FILE` and the `data-ds-one-translations`,
+     * `ds-one:translations` and `ds-one-translations` markers in the page win
+     * over it.
+     */
+    translationsFile?: string;
+    /** The localStorage key that keeps the chosen language. Defaults to `language`. */
+    storageKey?: string;
+    /**
+     * Report keys with no translation on the console, each once. Off by
+     * default, since components also show what people write themselves, and
+     * that is not a key anyone forgot. `window.DS_ONE_I18N_DEBUG = true` or
+     * localStorage `ds-one:i18n-debug` set to `on` turn it on as well.
+     */
+    reportMissingKeys?: boolean | (() => boolean);
+    /**
+     * Load Design system 1's shared interface words (buttons, sign-in, empty
+     * states, dates, language names) beneath the product's own words, so the
+     * product's text wins where both have a key. Off by default.
+     */
+    sharedWords?: boolean;
+    /**
+     * Which languages get an address prefix (`/ja/…`) and whether the default
+     * language has one; see `configureLanguageRouting`. Without `languages`
+     * here, the product's `languages` get a prefix.
+     */
+    routing?: LanguageRoutingOptions;
+};
+/**
+ * Every language Design system 1 orders, names and maps browser languages to:
+ * the list in `./languages` (`LANGUAGES`). A product turns on the ones it
+ * translates with `configureI18n({ languages })`.
+ */
+export declare const SUPPORTED_LANGUAGES: readonly Language[];
+declare global {
+    interface Window {
+        DS_ONE_TRANSLATIONS?: Record<string, TranslationData>;
+        DS_ONE_TRANSLATIONS_FILE?: string;
+        DS_ONE_I18N?: I18nOptions;
+        DS_ONE_I18N_DEBUG?: boolean;
+    }
+}
+/**
+ * Fetch a language's words when the page needs one it has not got: its own
+ * file, or the whole table when that file is missing. Does nothing unless
+ * `languageFile` is configured, since otherwise the whole table, with every
+ * language in it, is what the page loads at startup.
+ */
+export declare function loadLanguage(language: LanguageCode): Promise<void>;
+export declare function getLanguageDisplayName(code: LanguageCode, options?: {
+    locale?: string;
+}): string;
+/**
+ * The browser's language, as one the product speaks: the first of the
+ * browser's languages that fits. When none does, a product that configured
+ * its languages gets English; one that configured nothing gets the browser's
+ * own tag, since its words may still be loaded under it.
+ */
+export declare function getBrowserLanguage(): LanguageCode;
+export declare const currentLanguage: {
+    value: string;
+    set: (lang: LanguageCode) => void;
+};
+/**
+ * Set the language module up for a product (see `I18nOptions`). Call it
+ * straight after importing the module: the first translations are fetched
+ * once the code that imported it has run. Called later, it fetches the current
+ * language's file if one is now configured.
+ */
+export declare function configureI18n(next: I18nOptions): void;
+/**
+ * Load Design system 1's shared interface words beneath the product's own
+ * (what `configureI18n({ sharedWords: true })` does). They arrive in a chunk
+ * of their own, so products that do not use them do not carry them.
+ */
+export declare function loadSharedWords(): Promise<void>;
+/**
+ * A key's text in the current language, with its placeholders (`{name}` and
+ * `{{name}}` alike) filled from `params`.
+ */
+export declare function translate(key: string, params?: TranslationParams): string;
+/**
+ * A key's text in a given language, whatever the page's own language is (a
+ * drawing made for one language, say). The fallback order: the language, its
+ * primary subtag (`ja-JP` reads `ja`), its relatives (`nn` reads `nb`,
+ * `pt-BR` reads `pt`), English, then the key itself. In each, the product's
+ * words come before the shared words.
+ */
+export declare function textInLanguage(key: string, language: LanguageCode, params?: TranslationParams): string;
+export declare function hasTranslation(key: string, language?: LanguageCode): boolean;
+export declare function getText(key: string, params?: TranslationParams): string;
+export declare function getAvailableLanguages(): Promise<LanguageCode[]>;
+export declare function getAvailableLanguagesSync(): LanguageCode[];
+/**
+ * Add words to what is loaded: one language's (`loadTranslations("da", {…})`)
+ * or several at once (`loadTranslations({ en: {…}, da: {…} })`), from a JSON
+ * file or a TypeScript module of the same shape (a `Partial` table is fine).
+ * Components update as they do when a translation file arrives.
+ */
+export declare function loadTranslations(language: LanguageCode, translations: TranslationTable): void;
+export declare function loadTranslations(translations: TranslationsFile): void;
+export declare function setLanguage(language: LanguageCode): void;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/0-face/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../DS1/0-face/i18n.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAGlC,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB,CAAC;AAGF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,IAAI,CAAC;IACpE;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,QAAQ,EAAc,CAAC;AAMlE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACtD,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B;CACF;AAuVD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BlE;AAiFD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,MAAM,CA6CR;AAqCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAqBjD;AAoBD,eAAO,MAAM,eAAe;;gBAEL,YAAY;CAWlC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CA+BrD;AAeD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAU/C;AAyGD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAmBR;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,YAAoC,GAC7C,OAAO,CAkBT;AAGD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAEvE;AAGD,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAE/D;AAGD,wBAAgB,yBAAyB,IAAI,YAAY,EAAE,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,YAAY,EAAE,gBAAgB,GAC7B,IAAI,CAAC;AACR,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;AAoCvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAGxD"}