@svelstack/translator 0.9.0

package/dist/index.js

@@ -0,0 +1,410 @@
+// ../internal/utils.js
+var numberOfPluralParts = {
+  "af": 2,
+  "bn": 2,
+  "bg": 2,
+  "ca": 2,
+  "da": 2,
+  "de": 2,
+  "el": 2,
+  "en": 2,
+  "eo": 2,
+  "es": 2,
+  "et": 2,
+  "eu": 2,
+  "fa": 2,
+  "fi": 2,
+  "fo": 2,
+  "fur": 2,
+  "fy": 2,
+  "gl": 2,
+  "gu": 2,
+  "ha": 2,
+  "he": 2,
+  "hu": 2,
+  "is": 2,
+  "it": 2,
+  "ku": 2,
+  "lb": 2,
+  "ml": 2,
+  "mn": 2,
+  "mr": 2,
+  "nah": 2,
+  "nb": 2,
+  "ne": 2,
+  "nl": 2,
+  "nn": 2,
+  "no": 2,
+  "oc": 2,
+  "om": 2,
+  "or": 2,
+  "pa": 2,
+  "pap": 2,
+  "ps": 2,
+  "pt": 2,
+  "so": 2,
+  "sq": 2,
+  "sv": 2,
+  "sw": 2,
+  "ta": 2,
+  "te": 2,
+  "tk": 2,
+  "ur": 2,
+  "zu": 2,
+  "am": 2,
+  "bh": 2,
+  "fil": 2,
+  "fr": 2,
+  "gun": 2,
+  "hi": 2,
+  "hy": 2,
+  "ln": 2,
+  "mg": 2,
+  "nso": 2,
+  "pt_BR": 2,
+  "ti": 2,
+  "wa": 2,
+  "mk": 2,
+  "be": 3,
+  "bs": 3,
+  "hr": 3,
+  "ru": 3,
+  "sh": 3,
+  "sr": 3,
+  "uk": 3,
+  "cs": 3,
+  "sk": 3,
+  "ga": 3,
+  "lt": 3,
+  "lv": 3,
+  "pl": 3,
+  "ro": 3,
+  "sl": 4,
+  "mt": 4,
+  "cy": 4,
+  "ar": 6
+};
+function getNumberOfPluralParts(locale) {
+  const normalizedLocale = locale !== "pt_BR" && locale.length > 3 ? locale.substring(0, locale.lastIndexOf("_")) : locale;
+  return numberOfPluralParts[normalizedLocale] ?? 0;
+}
+function getLocaleNumber(locale, number) {
+  number = Math.abs(number);
+  const normalizedLocale = locale !== "pt_BR" && locale.length > 3 ? locale.substring(0, locale.lastIndexOf("_")) : locale;
+  switch (normalizedLocale) {
+    case "af":
+    case "bn":
+    case "bg":
+    case "ca":
+    case "da":
+    case "de":
+    case "el":
+    case "en":
+    case "eo":
+    case "es":
+    case "et":
+    case "eu":
+    case "fa":
+    case "fi":
+    case "fo":
+    case "fur":
+    case "fy":
+    case "gl":
+    case "gu":
+    case "ha":
+    case "he":
+    case "hu":
+    case "is":
+    case "it":
+    case "ku":
+    case "lb":
+    case "ml":
+    case "mn":
+    case "mr":
+    case "nah":
+    case "nb":
+    case "ne":
+    case "nl":
+    case "nn":
+    case "no":
+    case "oc":
+    case "om":
+    case "or":
+    case "pa":
+    case "pap":
+    case "ps":
+    case "pt":
+    case "so":
+    case "sq":
+    case "sv":
+    case "sw":
+    case "ta":
+    case "te":
+    case "tk":
+    case "ur":
+    case "zu":
+      return number === 1 ? 0 : 1;
+    case "am":
+    case "bh":
+    case "fil":
+    case "fr":
+    case "gun":
+    case "hi":
+    case "hy":
+    case "ln":
+    case "mg":
+    case "nso":
+    case "pt_BR":
+    case "ti":
+    case "wa":
+      return number < 2 ? 0 : 1;
+    case "be":
+    case "bs":
+    case "hr":
+    case "ru":
+    case "sh":
+    case "sr":
+    case "uk":
+      return number % 10 === 1 && number % 100 !== 11 ? 0 : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 10 || number % 100 >= 20) ? 1 : 2;
+    case "cs":
+    case "sk":
+      return number === 1 ? 0 : number >= 2 && number <= 4 ? 1 : 2;
+    case "ga":
+      return number === 1 ? 0 : number === 2 ? 1 : 2;
+    case "lt":
+      return number % 10 === 1 && number % 100 !== 11 ? 0 : number % 10 >= 2 && (number % 100 < 10 || number % 100 >= 20) ? 1 : 2;
+    case "sl":
+      return number % 100 === 1 ? 0 : number % 100 === 2 ? 1 : number % 100 === 3 || number % 100 === 4 ? 2 : 3;
+    case "mk":
+      return number % 10 === 1 ? 0 : 1;
+    case "mt":
+      return number === 1 ? 0 : number === 0 || number % 100 > 1 && number % 100 < 11 ? 1 : number % 100 > 10 && number % 100 < 20 ? 2 : 3;
+    case "lv":
+      return number === 0 ? 0 : number % 10 === 1 && number % 100 !== 11 ? 1 : 2;
+    case "pl":
+      return number === 1 ? 0 : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 12 || number % 100 > 14) ? 1 : 2;
+    case "cy":
+      return number === 1 ? 0 : number === 2 ? 1 : number === 8 || number === 11 ? 2 : 3;
+    case "ro":
+      return number === 1 ? 0 : number === 0 || number % 100 > 0 && number % 100 < 20 ? 1 : 2;
+    case "ar":
+      return number === 0 ? 0 : number === 1 ? 1 : number === 2 ? 2 : number % 100 >= 3 && number % 100 <= 10 ? 3 : number % 100 >= 11 && number % 100 <= 99 ? 4 : 5;
+    default:
+      return 0;
+  }
+}
+
+// src/formatter.js
+var ChainMessageFormatter = class {
+  /**
+   * @type {MessageFormatter[]}
+   */
+  #formatters;
+  /**
+   * @param {MessageFormatter[]} formatters - An array of message formatters.
+   */
+  constructor(formatters) {
+    this.#formatters = formatters;
+  }
+  /**
+   * Applies all formatters to the message sequentially.
+   * @param {string} message - The message to format.
+   * @param {import('types.js').MessageFormatterOptions} options - The options for formatting.
+   * @returns {string} The formatted message.
+   */
+  format(message, options) {
+    for (const formatter of this.#formatters) {
+      message = formatter.format(message, options);
+    }
+    return message;
+  }
+};
+var PluralMessageFormatter = class {
+  /**
+   * Formats the message based on the pluralization rules of the given language.
+   * @param {string} message - The message to format.
+   * @param {import('types.js').MessageFormatterOptions} options - The options for formatting.
+   * @returns {string} The formatted message.
+   */
+  format(message, options) {
+    var _a;
+    const count = (_a = options.parameters) == null ? void 0 : _a.count;
+    if (count === void 0) {
+      return message;
+    }
+    if (!message.includes("|")) {
+      if (getNumberOfPluralParts(options.language) > 0) {
+        options.report(new Error(`Translator(${options.domain}.${options.key}): Missing plural separator "|" in message.`));
+      }
+      return message;
+    }
+    const parts = message.split("|");
+    if (parts.length !== getNumberOfPluralParts(options.language)) {
+      options.report(new Error(`Translator(${options.domain}.${options.key}): Invalid number of plural parts in message, expected ${getNumberOfPluralParts(options.language)}, ${parts.length} given.`));
+    }
+    const number = typeof count === "string" ? parseInt(count, 10) : count;
+    if (isNaN(number)) {
+      options.report(new Error(`Translator(${options.domain}.${options.key}): Invalid count parameter, ${count} given.`));
+      return parts[0];
+    }
+    const partNumber = getLocaleNumber(options.language, number);
+    const part = parts[partNumber];
+    if (part == null) {
+      options.report(new Error(`Translator(${options.domain}.${options.key}): Missing plural part for language "${options.language}" and number ${number}.`));
+      return parts[0];
+    }
+    return part;
+  }
+};
+var ParameterMessageFormatter = class {
+  /**
+   * Formats the message by replacing placeholders with parameter values.
+   * @param {string} message - The message to format.
+   * @param {import('types.js').MessageFormatterOptions} options - The options for formatting.
+   * @returns {string} The formatted message.
+   */
+  format(message, options) {
+    const parameters = options.parameters;
+    if (parameters === void 0) {
+      return message;
+    }
+    return message.replace(/\{\s*(.*?)\s*}/g, (_, key) => {
+      const val = parameters[key];
+      if (val == null) {
+        return `{${key}}`;
+      }
+      return val.toString();
+    });
+  }
+};
+
+// src/index.js
+var Translator = class {
+  /**
+   * @private
+   * @type {Record<string, Record<string, string>> | undefined}
+   */
+  translations = void 0;
+  /**
+   * @private
+   * @type {Promise<any> | undefined}
+   */
+  _promise = void 0;
+  /**
+   * @private
+   * @type {string}
+   */
+  _language;
+  /**
+   * @private
+   * @type {(error: any) => void}
+   */
+  report;
+  /**
+   * @private
+   * @type {ChainMessageFormatter}
+   */
+  formatter = new ChainMessageFormatter([
+    new PluralMessageFormatter(),
+    new ParameterMessageFormatter()
+  ]);
+  /**
+   * @param {import('./types.js').TranslatorOptions} options - Configuration options for the Translator.
+   * @throws {Error} If the fallback language is not in the dictionaries.
+   */
+  constructor(options) {
+    this.options = options;
+    if (!(this.options.fallbackLanguage in this.options.dictionaries)) {
+      throw new Error(`Fallback language "${this.options.fallbackLanguage}" is not available in the dictionaries.`);
+    }
+    this._language = this.getLanguage(this.options.language);
+    this.report = this.options.report || function() {
+    };
+    this.load(this._language);
+  }
+  /**
+   * Changes the current language and reloads translations.
+   * @param {string} val - The new language to switch to.
+   * @returns {Promise<void>} Resolves when the language is successfully changed.
+   */
+  async changeLanguage(val) {
+    val = this.getLanguage(val);
+    if (this._language !== val) {
+      await this.load(val);
+      this._language = val;
+    }
+  }
+  /**
+   * Gets the current language.
+   * @returns {string} The currently set language.
+   */
+  get language() {
+    return this._language;
+  }
+  /**
+   * Waits for any ongoing translation loading to finish.
+   * @returns {Promise<void>} Resolves when loading is complete.
+   */
+  async wait() {
+    await this._promise;
+  }
+  /**
+   * Translates a key within a given domain using optional parameters.
+   * @param {string} domain - The domain of the translation key.
+   * @param {string} key - The key to translate.
+   * @param {Record<string, string|number>} [parameters] - Optional parameters for formatting the translation.
+   * @returns {string} The translated string, or a fallback if not found.
+   */
+  trans(domain, key, parameters) {
+    var _a;
+    if (this.translations === void 0) {
+      return "";
+    }
+    const translation = (_a = this.translations[domain]) == null ? void 0 : _a[key];
+    if (translation === void 0) {
+      return `${domain}.${key}`;
+    }
+    return this.formatter.format(translation, {
+      language: this._language,
+      domain,
+      key,
+      report: this.report,
+      parameters
+    });
+  }
+  /**
+   * Loads translations for a specified language.
+   * @private
+   * @param {string} lang - The language to load.
+   * @returns {Promise<void>} Resolves when the translations are loaded.
+   */
+  async load(lang) {
+    const dictionary = this.options.dictionaries[lang];
+    if (typeof dictionary === "function") {
+      const promise = this._promise = dictionary();
+      this.translations = await promise;
+      this._promise = void 0;
+    } else {
+      this.translations = dictionary;
+    }
+    this.changed();
+  }
+  /**
+   * Determines the appropriate language to use.
+   * @private
+   * @param {string} lang - The desired language.
+   * @returns {string} The language to use, falling back if necessary.
+   */
+  getLanguage(lang) {
+    return lang in this.options.dictionaries ? lang : this.options.fallbackLanguage;
+  }
+  /**
+   * Called when the translations/language have changed. Can be overridden in subclasses.
+   * @protected
+   */
+  changed() {
+  }
+};
+export {
+  Translator
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@svelstack/translator",
+	"version": "0.9.0",
+	"scripts": {
+		"build": "tsup && npm run prepack",
+		"prepack": "publint",
+		"check": "tsc --noEmit",
+		"test": "vitest"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./src/types.d.ts",
+	"exports": {
+		".": {
+			"types": "./src/types.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src/types.d.ts",
+		"*.d.ts",
+		"README.md"
+	],
+	"devDependencies": {
+		"publint": "^0.3.2",
+		"tsup": "^8.3.5",
+		"vite": "^6.0.7",
+		"vitest": "^2.1.8",
+		"@sveltejs/vite-plugin-svelte": "^5.0.3"
+	}
+}

package/src/types.d.ts

@@ -0,0 +1,74 @@
+type Dictionary = {
+	[domain: string]: Record<string, string>;
+};
+
+export type TranslatorOptions = {
+	language: string;
+	fallbackLanguage: string;
+	dictionaries: {
+		[lang: string]: (() => Promise<Dictionary>) | Dictionary;
+	},
+	report?: (error: any) => void;
+};
+
+export class Translator {
+
+	constructor(options: TranslatorOptions);
+
+	changeLanguage(val: string): Promise<void>;
+
+	get language(): string;
+
+	/**
+	 * Wait for the translations to be loaded.
+	 */
+	wait(): Promise<void>;
+
+	trans(domain: string, key: string, parameters?: Record<string, string|number>): string;
+
+	protected changed(): void;
+}
+
+export interface TypesafeTranslator<Mapping extends Record<string, Record<string, string>>> extends Translator {
+
+	trans<Domain extends keyof Mapping, Key extends keyof Mapping[Domain]>(
+		domain: Domain,
+		key: Key,
+		...rest: Mapping[Domain][Key] extends never ? [parameters?: undefined] : [parameters: Record<Mapping[Domain][Key], string>]
+	): string;
+
+}
+
+export interface MessageFormatter {
+
+	format(message: string, options: MessageFormatterOptions): string;
+
+}
+
+export type MessageFormatterOptions = {
+	language: string;
+	domain: string;
+	key: string;
+	report: (error: any) => void;
+	parameters?: Record<string, string|number>;
+};
+
+export class ChainMessageFormatter implements MessageFormatter {
+
+	constructor(formatters: MessageFormatter[]);
+
+	format(message: string, options: MessageFormatterOptions): string;
+
+}
+
+export class PluralMessageFormatter implements MessageFormatter {
+
+	format(message: string, options: MessageFormatterOptions): string;
+
+}
+
+export class ParameterMessageFormatter implements MessageFormatter {
+
+	format(message: string, options: MessageFormatterOptions): string;
+
+}