@form-engine-ts/translator-i18next 4.1.0 → 4.2.0

package/README.md

@@ -20,4 +20,14 @@ translator.translate("builder.questionTitle", "ja", { count: 2 });
 
 The adapter passes the requested locale as `lng` and returns `undefined` for missing keys when i18next's `exists`
 method reports that the key is unavailable. This allows form-engine-ts to use its normal fallback catalog and legacy
-translation aliases.
+translation aliases. Use `keyPrefix` for catalogs nested below a namespace and `fallbackLocales` to try additional
+locales:
+
+```ts
+const translator = createI18nextTranslator({
+  i18n,
+  namespace: "common",
+  keyPrefix: "formEngine",
+  fallbackLocales: ["ja"]
+});
+```

package/dist/index.cjs

@@ -30,20 +30,36 @@ function isNonEmptyString(value) {
 function isUnresolvedKey(value, key) {
   return value === key || value.endsWith(`.${key}`) || value.endsWith(`:${key}`);
 }
-function createAdapter({ i18n, namespace, checkUnresolvedKey = true }) {
+function createAdapter({
+  i18n,
+  namespace,
+  keyPrefix,
+  fallbackLocales,
+  checkUnresolvedKey = true
+}) {
   if (i18n === null || typeof i18n !== "object" || typeof i18n.t !== "function") {
     throw new TypeError("i18next adapter requires an i18next instance with a t function.");
   }
   return {
     translate(key, locale, params = {}) {
-      const lookupOptions = { ...params, lng: locale };
-      if (namespace !== void 0) lookupOptions.ns = namespace;
+      const prefixedKey = keyPrefix === void 0 ? key : `${keyPrefix}.${key}`;
+      const lookupKey = keyPrefix === void 0 ? key : namespace === void 0 ? prefixedKey : `${namespace}:${prefixedKey}`;
+      const locales = [locale, ...(fallbackLocales ?? []).filter((fallback) => fallback !== locale)];
       const exists = i18n.exists;
-      const canCheckExistence = exists !== void 0;
-      if (exists !== void 0 && !exists(key, lookupOptions)) return void 0;
-      const result = i18n.t(key, lookupOptions);
-      if (!isNonEmptyString(result)) return void 0;
-      return !canCheckExistence && checkUnresolvedKey && isUnresolvedKey(result, key) ? void 0 : result;
+      for (const candidateLocale of locales) {
+        const lookupOptions = { ...params, lng: candidateLocale };
+        if (keyPrefix === void 0 && namespace !== void 0) lookupOptions.ns = namespace;
+        if (keyPrefix !== void 0) lookupOptions.defaultValue = void 0;
+        if (exists !== void 0 && !exists(lookupKey, lookupOptions)) continue;
+        const result = i18n.t(lookupKey, lookupOptions);
+        if (!isNonEmptyString(result)) continue;
+        if (checkUnresolvedKey && isUnresolvedKey(result, lookupKey)) continue;
+        if (keyPrefix !== void 0 && (result === lookupKey || result === prefixedKey || result === key || result.endsWith(key))) {
+          continue;
+        }
+        return result;
+      }
+      return void 0;
     }
   };
 }

package/dist/index.d.cts

@@ -4,11 +4,21 @@ interface I18nextInstance {
     t(key: string, options?: Readonly<Record<string, unknown>>): unknown;
     exists?(key: string, options?: Readonly<Record<string, unknown>>): boolean;
 }
+interface I18nextAdapterOptions {
+    /** Optional namespace passed to i18next for every lookup. */
+    readonly namespace?: string;
+    /** Optional key prefix nested inside the namespace. */
+    readonly keyPrefix?: string;
+    /** Locales to try after the requested locale cannot resolve the key. */
+    readonly fallbackLocales?: readonly string[];
+    /** Treat a result equal to the lookup key as unresolved. */
+    readonly checkUnresolvedKey?: boolean;
+}
 interface I18nextTranslatorOptions {
     readonly i18n: I18nextInstance;
-    /** Optional namespace passed to i18next for every lookup. */
     readonly namespace?: string;
-    /** Treat a result equal to the lookup key as unresolved when `exists` is unavailable. */
+    readonly keyPrefix?: string;
+    readonly fallbackLocales?: readonly string[];
     readonly checkUnresolvedKey?: boolean;
 }
 /** Create a form-engine translation adapter from an i18next instance. */
@@ -16,4 +26,4 @@ declare function createI18nextTranslator(options: I18nextTranslatorOptions): Tra
 /** Convenience overload for callers that already have the i18next instance. */
 declare function createI18nextTranslationAdapter(i18n: I18nextInstance, options?: Omit<I18nextTranslatorOptions, "i18n">): TranslationAdapter;
 
-export { type I18nextInstance, type I18nextTranslatorOptions, createI18nextTranslationAdapter, createI18nextTranslator };
+export { type I18nextAdapterOptions, type I18nextInstance, type I18nextTranslatorOptions, createI18nextTranslationAdapter, createI18nextTranslator };

package/dist/index.d.ts

@@ -4,11 +4,21 @@ interface I18nextInstance {
     t(key: string, options?: Readonly<Record<string, unknown>>): unknown;
     exists?(key: string, options?: Readonly<Record<string, unknown>>): boolean;
 }
+interface I18nextAdapterOptions {
+    /** Optional namespace passed to i18next for every lookup. */
+    readonly namespace?: string;
+    /** Optional key prefix nested inside the namespace. */
+    readonly keyPrefix?: string;
+    /** Locales to try after the requested locale cannot resolve the key. */
+    readonly fallbackLocales?: readonly string[];
+    /** Treat a result equal to the lookup key as unresolved. */
+    readonly checkUnresolvedKey?: boolean;
+}
 interface I18nextTranslatorOptions {
     readonly i18n: I18nextInstance;
-    /** Optional namespace passed to i18next for every lookup. */
     readonly namespace?: string;
-    /** Treat a result equal to the lookup key as unresolved when `exists` is unavailable. */
+    readonly keyPrefix?: string;
+    readonly fallbackLocales?: readonly string[];
     readonly checkUnresolvedKey?: boolean;
 }
 /** Create a form-engine translation adapter from an i18next instance. */
@@ -16,4 +26,4 @@ declare function createI18nextTranslator(options: I18nextTranslatorOptions): Tra
 /** Convenience overload for callers that already have the i18next instance. */
 declare function createI18nextTranslationAdapter(i18n: I18nextInstance, options?: Omit<I18nextTranslatorOptions, "i18n">): TranslationAdapter;
 
-export { type I18nextInstance, type I18nextTranslatorOptions, createI18nextTranslationAdapter, createI18nextTranslator };
+export { type I18nextAdapterOptions, type I18nextInstance, type I18nextTranslatorOptions, createI18nextTranslationAdapter, createI18nextTranslator };

package/dist/index.js

@@ -5,20 +5,36 @@ function isNonEmptyString(value) {
 function isUnresolvedKey(value, key) {
   return value === key || value.endsWith(`.${key}`) || value.endsWith(`:${key}`);
 }
-function createAdapter({ i18n, namespace, checkUnresolvedKey = true }) {
+function createAdapter({
+  i18n,
+  namespace,
+  keyPrefix,
+  fallbackLocales,
+  checkUnresolvedKey = true
+}) {
   if (i18n === null || typeof i18n !== "object" || typeof i18n.t !== "function") {
     throw new TypeError("i18next adapter requires an i18next instance with a t function.");
   }
   return {
     translate(key, locale, params = {}) {
-      const lookupOptions = { ...params, lng: locale };
-      if (namespace !== void 0) lookupOptions.ns = namespace;
+      const prefixedKey = keyPrefix === void 0 ? key : `${keyPrefix}.${key}`;
+      const lookupKey = keyPrefix === void 0 ? key : namespace === void 0 ? prefixedKey : `${namespace}:${prefixedKey}`;
+      const locales = [locale, ...(fallbackLocales ?? []).filter((fallback) => fallback !== locale)];
       const exists = i18n.exists;
-      const canCheckExistence = exists !== void 0;
-      if (exists !== void 0 && !exists(key, lookupOptions)) return void 0;
-      const result = i18n.t(key, lookupOptions);
-      if (!isNonEmptyString(result)) return void 0;
-      return !canCheckExistence && checkUnresolvedKey && isUnresolvedKey(result, key) ? void 0 : result;
+      for (const candidateLocale of locales) {
+        const lookupOptions = { ...params, lng: candidateLocale };
+        if (keyPrefix === void 0 && namespace !== void 0) lookupOptions.ns = namespace;
+        if (keyPrefix !== void 0) lookupOptions.defaultValue = void 0;
+        if (exists !== void 0 && !exists(lookupKey, lookupOptions)) continue;
+        const result = i18n.t(lookupKey, lookupOptions);
+        if (!isNonEmptyString(result)) continue;
+        if (checkUnresolvedKey && isUnresolvedKey(result, lookupKey)) continue;
+        if (keyPrefix !== void 0 && (result === lookupKey || result === prefixedKey || result === key || result.endsWith(key))) {
+          continue;
+        }
+        return result;
+      }
+      return void 0;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/translator-i18next",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "4.1.0"
+    "@form-engine-ts/core": "4.2.0"
   },
   "peerDependencies": {
     "i18next": ">=22.0.0"