i18n-keyless-core 2.4.2 → 2.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { AVAILABLE_LANGS, DEFAULT_NAMESPACE } from "./types.ts";
 export type { Lang, PrimaryLang, Translations, TranslationsUsage, HandleTranslateFunction, GetAllTranslationsFunction, SendTranslationsUsageFunction, GetAllTranslationsForAllLanguagesFunction, LanguagesConfig, LastRefresh, UniqueId, I18nKeylessRequestBody, I18nKeylessResponse, I18nKeylessTranslationsUsageRequestBody, I18nKeylessAllTranslationsResponse, FetchTranslationParams, TranslationOptions } from "./types.ts";
-export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, queue } from "./service.ts";
+export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, resolveOriginLanguage, queue } from "./service.ts";
 export { api } from "./api.ts";

package/dist/index.js

@@ -1,3 +1,3 @@
 export { AVAILABLE_LANGS, DEFAULT_NAMESPACE } from "./types.js";
-export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, queue } from "./service.js";
+export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, resolveOriginLanguage, queue } from "./service.js";
 export { api } from "./api.js";

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "i18n-keyless-core",
     "private": false,
-    "version": "2.4.2",
+    "version": "2.5.0",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",

package/dist/service.d.ts

@@ -6,6 +6,11 @@ export declare const queue: MyPQueue;
  * `namespace` wins, then the config-level `defaultNamespace`, then `DEFAULT_NAMESPACE`.
  */
 export declare function resolveNamespace(options: TranslationOptions | undefined, config: FetchTranslationParams["config"]): string;
+/**
+ * Resolves the effective origin language of a key (UGC flow): the per-call `originLanguage`
+ * when it exists and differs from the primary language, undefined otherwise (regular flow).
+ */
+export declare function resolveOriginLanguage(options: TranslationOptions | undefined, config: Pick<FetchTranslationParams["config"], "languages">): Lang | undefined;
 /**
  * Returns the namespaces queued since the last call (with their `unpersisted` flag) and
  * clears the map.

package/dist/service.js

@@ -10,6 +10,17 @@ export const queue = new MyPQueue({ concurrency: 30 });
 export function resolveNamespace(options, config) {
     return options?.namespace || config.defaultNamespace || DEFAULT_NAMESPACE;
 }
+/**
+ * Resolves the effective origin language of a key (UGC flow): the per-call `originLanguage`
+ * when it exists and differs from the primary language, undefined otherwise (regular flow).
+ */
+export function resolveOriginLanguage(options, config) {
+    const originLanguage = options?.originLanguage;
+    if (!originLanguage || originLanguage === config.languages.primary) {
+        return undefined;
+    }
+    return originLanguage;
+}
 /**
  * Scratchpad of namespaces that had at least one missing key queued for translation since
  * the last bulk fetch (mapped to whether that namespace is `unpersisted`). The queue's
@@ -45,8 +56,13 @@ export function getTranslationCore(key, store, options) {
     if (!config.API_KEY) {
         throw new Error("i18n-keyless: config is not initialized");
     }
+    // The language the key is already written in: the primary language, except for UGC
+    // (originLanguage). When the current language is that one, the key renders as-is —
+    // notably, a UGC key DOES need a lookup/translation when the current language is the
+    // primary one (its primary version is an AI translation, not the key itself).
+    const sourceLanguage = resolveOriginLanguage(options, config) ?? config.languages.primary;
     let translation = key;
-    if (currentLanguage === config.languages.primary) {
+    if (currentLanguage === sourceLanguage) {
         translation = key;
     }
     else {
@@ -135,6 +151,7 @@ export function translateKey(key, store, options) {
                     forceTemporary: options?.forceTemporary,
                     languages: config.languages.supported,
                     primaryLanguage: config.languages.primary,
+                    originLanguage: resolveOriginLanguage(options, config),
                 };
                 const apiUrl = config.API_URL || "https://api.i18n-keyless.com";
                 const url = `${apiUrl}/translate`;

package/dist/types.d.ts

@@ -103,6 +103,14 @@ export type TranslationOptions = {
      * RegEx is `key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))` so you can use use your own syntax.
      */
     replace?: Record<string, string>;
+    /**
+     * The language the text is written in when it differs from the primary language —
+     * i.e. user generated content (UGC). The backend translates it into the primary language,
+     * keeps the raw text for viewers in that language, and AI-translates all the others.
+     * When the current language IS the origin language, the text is rendered as-is (no API call).
+     * Omitted or equal to the primary language means the regular flow.
+     */
+    originLanguage?: Lang;
 };
 export interface I18nKeylessRequestBody {
     key: string;
@@ -111,6 +119,13 @@ export interface I18nKeylessRequestBody {
     forceTemporary?: TranslationOptions["forceTemporary"];
     languages: LanguagesConfig["supported"];
     primaryLanguage: LanguagesConfig["primary"];
+    /**
+     * Language the `key` text is written in when it differs from the primary language (UGC flow).
+     * The backend translates `key` into the primary language, keys the row by that primary text,
+     * stores the raw `key` in the origin-language cell, and AI-translates all other languages.
+     * Omitted or equal to `primaryLanguage` means the regular flow.
+     */
+    originLanguage?: Lang;
 }
 export interface I18nKeylessTranslationsUsageRequestBody {
     primaryLanguage: LanguagesConfig["primary"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18n-keyless-core",
   "private": false,
-  "version": "2.4.2",
+  "version": "2.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",