@koine/i18n 2.0.0-beta.203 → 2.0.0-beta.205

package/LLM.md

@@ -0,0 +1,23 @@
+# Prompts
+
+To localize a project start by looking at applications source code. Each should have a `i18n` folder where `@koine/i18n` generates various i18n related source files, for instance translations functions are created in `$t` subfolder. These functions are used to output localised text.
+Divide the localization process in these phases:
+
+1. Go through applications codebase and extract all strings. By "extract" I mean you should get the string value and assign it to a unique key. All they keys you gather will construct a single JSON object with various levels of nested objects. Each nested level represent a portion of the path where the string was found. For instance if you find "Hello world" in `/src/components/header.tsx -> HeaderButton component` the key will be `header.button.text` where the *first* level is the relative path to the file, the *second* level is the component name (excluding the folder name), and the *third* level is the text key based on what the component does. Constructing the key is up to you, but it should be unique and descriptive, not too long or complex. Note: you should ignore `src/components` and `src/app` folders when constructing the key. You must hold in your memory a reference of the key and its position in the codebase as that will need to be replaced at step 5.
+It is very important to understand the needed interpolation and plurals when extracting the strings, you might need:
+  - a **simple** interpolated value: `{ myKey: "example of a {{ dynamicValue }}" }`
+  - a **component** based interpolated value: `{ myKey: "example of <dynamic-value></dynamic-value>" }`
+  - a **plural** formatted value: `{ myKey: { one: "example of a plural form", other: "example of some plural forms" } }`.
+
+2. Now you have a JSON object with all the strings you need to localize. You need to create a new file in the `i18n` folder mentioned above called `{locale}.json` and save the JSON object to it, where `{locale}` is the language code the text are written in the application source code.
+
+3. Now setup the `@koine/i18n` compiler (if not already set) in the application codebase, it should use as `source` the just generated JSON files for each language.
+
+4. Run the compiler.
+
+5. Now look into the `i18n` folder containing the generated artifacts and use the generated `$t` functions to replace the hardcoded string in the codebase. The function names reflect the keys so you should just match those. Do not pass the locale to each `$t` function invokation, that is set globally and all `$t` function will read it from there. Here how you should treat interpolation gathered at step 1:
+  - a **simple** interpolated value will just use first function argument, e.g. `$t_myKey({ dynamicValue: "user name" })`
+  - a **component** based interpolated value should use `TransText` component from the `i18n` folder generated artifacts (typically importable in TypeScript from `@/i18n`), .e.g. `<TransText text={$t_myKey()} components={{ "dynamic-value": () => <b>Whatever JSX</b> }}> />`
+  - a **plural** formatted value uses `count` special function argument value, e.g. `$t_myKey({ count: 3 })`
+  
+When asked to localize an application for the first time go through all the steps, when done already you can only look for untranslated strings in step 1 and skip step 3.

package/adapter-js/generators/loadTranslations.cjs.js

@@ -3,7 +3,7 @@
 var createAdapter = require('../../compiler/createAdapter.cjs.js');
 var helpers = require('../../compiler/helpers.cjs.js');
 
-var l = createAdapter.createGenerator("js", (n)=>({
+var l = createAdapter.createGenerator("js", ({ input: n })=>({
         loadTranslations: {
             dir: createAdapter.createGenerator.dirs.internal,
             name: "loadTranslations",
@@ -18,10 +18,9 @@ import type { I18n } from "../types";
 export const loadTranslations = (
   locale: I18n.Locale,
   namespace: I18n.TranslationsNamespace,
-) =>
-  import(\`${helpers.getTranslationsDir(1)}/\${locale}/\${namespace}.json\`).then(
+) => ${n.translationFiles?.length ? `\n  import(\`${helpers.getTranslationsDir(1)}/\${locale}/\${namespace}.json\`).then(
     (m) => m.default,
-  );
+  )` : "{}"};
 `
         }
     }));

package/adapter-js/generators/loadTranslations.esm.js

@@ -1,7 +1,7 @@
 import { createGenerator } from '../../compiler/createAdapter.esm.js';
 import { getTranslationsDir } from '../../compiler/helpers.esm.js';
 
-var l = createGenerator("js", (n)=>({
+var l = createGenerator("js", ({ input: n })=>({
         loadTranslations: {
             dir: createGenerator.dirs.internal,
             name: "loadTranslations",
@@ -16,10 +16,9 @@ import type { I18n } from "../types";
 export const loadTranslations = (
   locale: I18n.Locale,
   namespace: I18n.TranslationsNamespace,
-) =>
-  import(\`${getTranslationsDir(1)}/\${locale}/\${namespace}.json\`).then(
+) => ${n.translationFiles?.length ? `\n  import(\`${getTranslationsDir(1)}/\${locale}/\${namespace}.json\`).then(
     (m) => m.default,
-  );
+  )` : "{}"};
 `
         }
     }));

package/adapter-next/index.cjs.js

@@ -19,15 +19,15 @@ var i18nGet = require('./generators/router-pages/i18nGet.cjs.js');
 var useRouteId = require('./generators/useRouteId.cjs.js');
 var webpackDefine = require('./generators/webpack-define.cjs.js');
 
-function resolveGlobalizeOption(e) {
-    let { functions: r, prefix: t } = e;
+function resolveGlobalizeOption(r) {
+    let { functions: e, prefix: t } = r;
     return {
         prefix: t || "",
         prefixSafe: t ? (t + "_").replace(/_+$/, "_") : "",
-        functions: "boolean" == typeof r ? {
+        functions: "boolean" == typeof e ? {
             routes: true,
             translations: true
-        } : r
+        } : e
     };
 }
 const adapterNext = createAdapter.createAdapter({
@@ -35,6 +35,7 @@ const adapterNext = createAdapter.createAdapter({
     defaultOptions: {
         ...index.adapterReact.defaultOptions,
         router: "app",
+        modularizeI18nImports: true,
         globalize: {
             prefix: "i18n",
             functions: true
@@ -47,10 +48,10 @@ const adapterNext = createAdapter.createAdapter({
             nextVersion: o
         };
     },
-    getGenerators: (e)=>{
-        let { router: t } = e.options.adapter.options;
+    getGenerators: (r)=>{
+        let { router: t } = r.options.adapter.options;
         return [
-            ...index.adapterReact.getGenerators(e),
+            ...index.adapterReact.getGenerators(r),
             nextRedirects,
             nextRewrites,
             ..."app" === t || "migrating" === t ? [
@@ -70,11 +71,11 @@ const adapterNext = createAdapter.createAdapter({
             webpackDefine
         ];
     },
-    getTransformers: (e)=>{
-        let { router: r } = e.options.adapter.options;
+    getTransformers: (r)=>{
+        let { router: e } = r.options.adapter.options;
         return {
             I18nHeadTags: false,
-            ..."app" === r ? {
+            ..."app" === e ? {
                 I18nEffects: false
             } : {}
         };

package/adapter-next/index.d.ts

@@ -4,6 +4,11 @@ export type Options = AdapterReact.Options & {
      * @default "app"
      */
     router: "app" | "pages" | "migrating";
+    /**
+     * Uses `swc` transforms to modularize i18n imports with NextJS `modularizeImports` option
+     * @default true
+     */
+    modularizeI18nImports?: boolean;
     /**
      * Configure the generation of globally exposed api
      */
@@ -203,6 +208,7 @@ export declare const adapterNext: {
     getMeta: <TAdapterName extends import("../compiler").I18nCompiler.AdapterName>(options: import("../compiler").I18nCompiler.AdapterConfigurationResolved<TAdapterName>["options"]) => import("../compiler").I18nCompiler.AdapterConfigurationResolved<import("../compiler").I18nCompiler.AdapterName>["meta"];
     defaultOptions: {
         router: "app";
+        modularizeI18nImports: true;
         globalize: {
             prefix: string;
             functions: true;

package/adapter-next/index.esm.js

@@ -15,15 +15,15 @@ import d from './generators/router-pages/i18nGet.esm.js';
 import l from './generators/useRouteId.esm.js';
 import c from './generators/webpack-define.esm.js';
 
-function resolveGlobalizeOption(e) {
-    let { functions: r, prefix: t } = e;
+function resolveGlobalizeOption(r) {
+    let { functions: e, prefix: t } = r;
     return {
         prefix: t || "",
         prefixSafe: t ? (t + "_").replace(/_+$/, "_") : "",
-        functions: "boolean" == typeof r ? {
+        functions: "boolean" == typeof e ? {
             routes: true,
             translations: true
-        } : r
+        } : e
     };
 }
 const adapterNext = createAdapter({
@@ -31,6 +31,7 @@ const adapterNext = createAdapter({
     defaultOptions: {
         ...adapterReact.defaultOptions,
         router: "app",
+        modularizeI18nImports: true,
         globalize: {
             prefix: "i18n",
             functions: true
@@ -43,10 +44,10 @@ const adapterNext = createAdapter({
             nextVersion: o
         };
     },
-    getGenerators: (e)=>{
-        let { router: t } = e.options.adapter.options;
+    getGenerators: (r)=>{
+        let { router: t } = r.options.adapter.options;
         return [
-            ...adapterReact.getGenerators(e),
+            ...adapterReact.getGenerators(r),
             o,
             a,
             ..."app" === t || "migrating" === t ? [
@@ -66,11 +67,11 @@ const adapterNext = createAdapter({
             c
         ];
     },
-    getTransformers: (e)=>{
-        let { router: r } = e.options.adapter.options;
+    getTransformers: (r)=>{
+        let { router: e } = r.options.adapter.options;
         return {
             I18nHeadTags: false,
-            ..."app" === r ? {
+            ..."app" === e ? {
                 I18nEffects: false
             } : {}
         };

package/adapter-next/plugin/utils.cjs.js

@@ -13,32 +13,32 @@ function shouldIgnoreNextJsConfigRun() {
 function transformPathname(e, t) {
     return "/" + e.split("/").filter(Boolean).map((e)=>e.startsWith("[[...") ? `:${encodeURIComponent(e.slice(5, -2))}` : e.startsWith("[[") ? `:${encodeURIComponent(e.slice(2, -2))}` : e.startsWith("[") ? `:${encodeURIComponent(e.slice(1, -1))}` : `${encodeURIComponent(e)}`).join("/") + (t ? "/:wildcard*" : "");
 }
-let tweakNextConfig = (n, i, l)=>{
-    let { config: { defaultLocale: a, locales: p }, options: { routes: { localeParamName: c }, write: f } } = i, { webpack: u, i18n: m, modularizeImports: d = {}, ...w } = l, g = {
-        ...w,
+let tweakNextConfig = (n, i, a)=>{
+    let { config: { defaultLocale: l, locales: p }, options: { adapter: { options: { modularizeI18nImports: c } }, routes: { localeParamName: f }, write: u } } = i, { webpack: m, i18n: d, modularizeImports: w = {}, ...g } = a, R = {
+        ...g,
         modularizeImports: {
-            ...createSwcTransforms.createSwcTransforms(i.options),
-            ...d
+            ...createSwcTransforms.createSwcTransforms(i.options, c),
+            ...w
         },
         ...n.webpackPlugin && {
             webpack: (r, i)=>{
-                let l = "function" == typeof u ? u(r, i) : r;
+                let a = "function" == typeof m ? m(r, i) : r;
                 return {
-                    ...l,
+                    ...a,
                     plugins: [
-                        ...l.plugins || [],
+                        ...a.plugins || [],
                         new webpackPluginI18n.I18nWebpackPlugin(n),
                         new webpack.ContextReplacementPlugin(/^date-fns[/\\]locale$/, RegExp(`\\.[/\\\\](${p.join("|")})[/\\\\]index\\.js$`)),
-                        f && new webpack.DefinePlugin(require(path.join(f.cwd, f.output, "internal/webpack-define-granular.cjs")))
+                        u && new webpack.DefinePlugin(require(path.join(u.cwd, u.output, "internal/webpack-define-granular.cjs")))
                     ].filter(Boolean)
                 };
             }
         }
     };
-    return c ? delete g.i18n : (g.i18n = g.i18n || {
+    return f ? delete R.i18n : (R.i18n = R.i18n || {
         locales: p,
-        defaultLocale: a
-    }, g.i18n.locales = p, g.i18n.defaultLocale = a), g;
+        defaultLocale: l
+    }, R.i18n.locales = p, R.i18n.defaultLocale = l), R;
 };
 let getRedirects = async (e, t)=>{
     let o = redirects.generateRedirects(t.config, t.options.routes, t.routes.byId);

package/adapter-next/plugin/utils.d.ts

@@ -1,5 +1,6 @@
 import type { NextConfig } from "next";
 import type { I18nCompilerOptions, I18nCompilerReturn } from "../../compiler";
+import type { I18nCompilerReturnForAdapter } from "../../compiler/api";
 /**
  * `next.config` runs twice, running the compiler only once is enough, the condition
  * is dependent on the environment as
@@ -24,7 +25,7 @@ export type I18nCompilerOptionsNext = {
      */
     webpackPlugin?: boolean;
 };
-export declare let tweakNextConfig: (i18nCompilerOptions: I18nCompilerOptions & I18nCompilerOptionsNext, i18nCompilerReturn: I18nCompilerReturn, options: NextConfig) => NextConfig;
+export declare let tweakNextConfig: (i18nCompilerOptions: I18nCompilerOptions & I18nCompilerOptionsNext, i18nCompilerReturn: I18nCompilerReturnForAdapter<"next">, options: NextConfig) => NextConfig;
 export declare let getRedirects: (prevRedirects: NextConfig["redirects"], i18nResult: I18nCompilerReturn) => Promise<import("next/dist/lib/load-custom-routes").Redirect[]>;
 export declare let getRewrites: (prevRewrites: NextConfig["rewrites"], i18nResult: I18nCompilerReturn) => Promise<{
     beforeFiles: import("next/dist/lib/load-custom-routes").Rewrite[];

package/adapter-next/plugin/utils.esm.js

@@ -11,32 +11,32 @@ function shouldIgnoreNextJsConfigRun() {
 function transformPathname(e, t) {
     return "/" + e.split("/").filter(Boolean).map((e)=>e.startsWith("[[...") ? `:${encodeURIComponent(e.slice(5, -2))}` : e.startsWith("[[") ? `:${encodeURIComponent(e.slice(2, -2))}` : e.startsWith("[") ? `:${encodeURIComponent(e.slice(1, -1))}` : `${encodeURIComponent(e)}`).join("/") + (t ? "/:wildcard*" : "");
 }
-let tweakNextConfig = (n, i, l)=>{
-    let { config: { defaultLocale: a, locales: p }, options: { routes: { localeParamName: c }, write: f } } = i, { webpack: u, i18n: m, modularizeImports: d = {}, ...w } = l, g = {
-        ...w,
+let tweakNextConfig = (n, i, a)=>{
+    let { config: { defaultLocale: l, locales: p }, options: { adapter: { options: { modularizeI18nImports: c } }, routes: { localeParamName: f }, write: u } } = i, { webpack: m, i18n: d, modularizeImports: w = {}, ...g } = a, R = {
+        ...g,
         modularizeImports: {
-            ...createSwcTransforms(i.options),
-            ...d
+            ...createSwcTransforms(i.options, c),
+            ...w
         },
         ...n.webpackPlugin && {
             webpack: (r, i)=>{
-                let l = "function" == typeof u ? u(r, i) : r;
+                let a = "function" == typeof m ? m(r, i) : r;
                 return {
-                    ...l,
+                    ...a,
                     plugins: [
-                        ...l.plugins || [],
+                        ...a.plugins || [],
                         new I18nWebpackPlugin(n),
                         new ContextReplacementPlugin(/^date-fns[/\\]locale$/, RegExp(`\\.[/\\\\](${p.join("|")})[/\\\\]index\\.js$`)),
-                        f && new DefinePlugin(require(join(f.cwd, f.output, "internal/webpack-define-granular.cjs")))
+                        u && new DefinePlugin(require(join(u.cwd, u.output, "internal/webpack-define-granular.cjs")))
                     ].filter(Boolean)
                 };
             }
         }
     };
-    return c ? delete g.i18n : (g.i18n = g.i18n || {
+    return f ? delete R.i18n : (R.i18n = R.i18n || {
         locales: p,
-        defaultLocale: a
-    }, g.i18n.locales = p, g.i18n.defaultLocale = a), g;
+        defaultLocale: l
+    }, R.i18n.locales = p, R.i18n.defaultLocale = l), R;
 };
 let getRedirects = async (e, t)=>{
     let o = generateRedirects(t.config, t.options.routes, t.routes.byId);

package/compiler/api.d.ts

@@ -1,7 +1,8 @@
-import { type CodeDataOptions, type CodeWriteOptions } from "./code";
+import { type CodeDataOptions, type CodeDataOptionsResolved, type CodeWriteOptions } from "./code";
 import { type I18nCompilerConfig } from "./config";
 import { type InputDataOptions, type InputWriteOptions } from "./input";
 import { type SummaryDataOptions, type SummaryWriteOptions } from "./summary";
+import type { I18nCompiler } from "./types";
 type OptionsInput = InputDataOptions & {
     /**
      * Options for _input_ writing
@@ -33,10 +34,13 @@ export type I18nCompilerOptions = I18nCompilerConfig & {
     };
 };
 export type I18nCompilerReturn = Awaited<ReturnType<typeof i18nCompiler>>;
+export type I18nCompilerReturnForAdapter<TAdapterName extends I18nCompiler.AdapterName> = Omit<I18nCompilerReturn, "options"> & {
+    options: CodeDataOptionsResolved<TAdapterName>;
+};
 /**
  * i18nCompiler async api
  *
  * @public
  */
-export declare let i18nCompiler: (options: I18nCompilerOptions) => Promise<import("./types").I18nCompiler.DataCode<import("./types").I18nCompiler.AdapterName>>;
+export declare let i18nCompiler: (options: I18nCompilerOptions) => Promise<I18nCompiler.DataCode<I18nCompiler.AdapterName>>;
 export {};

package/compiler/code/write.cjs.js

@@ -43,7 +43,7 @@ function resolveWriteCodeOptions(t) {
         output: o,
         emptyOutputFolder: i,
         ignorePaths: n,
-        tsconfig: {
+        tsconfig: false !== r && {
             path: "../tsconfig.json",
             alias: `@/${o.split(node_path.sep).filter(Boolean).pop() || "i18n"}`,
             ...r

package/compiler/code/write.esm.js

@@ -22,7 +22,7 @@ function resolveWriteCodeOptions(t) {
         output: o,
         emptyOutputFolder: i,
         ignorePaths: n,
-        tsconfig: {
+        tsconfig: false !== r && {
             path: "../tsconfig.json",
             alias: `@/${o.split(sep).filter(Boolean).pop() || "i18n"}`,
             ...r

package/compiler/createSwcTransforms.cjs.js

@@ -2,14 +2,14 @@
 
 var swc = require('@koine/node/swc');
 
-let createSwcTransforms = (e)=>{
-    let { write: o } = e, n = o?.tsconfig ? o.tsconfig.alias : "";
+let createSwcTransforms = (e, o)=>{
+    let { write: n } = e, r = n?.tsconfig ? n.tsconfig.alias : "";
     return {
         ...swc.swcCreateTransform({
             path: "@koine/i18n"
         }),
-        ...n ? swc.swcCreateTransform({
-            path: n
+        ...o && r ? swc.swcCreateTransform({
+            path: r
         }) : {}
     };
 };

package/compiler/createSwcTransforms.d.ts

@@ -3,7 +3,9 @@ import type { CodeDataOptionsResolved } from "./code";
 /**
  * Automatically create swc transforms based on given options
  */
-export declare let createSwcTransforms: (resolvedOptions: PickDeep<CodeDataOptionsResolved, "write.tsconfig">) => {
+export declare let createSwcTransforms: (resolvedOptions: PickDeep<CodeDataOptionsResolved, "write.tsconfig">, 
+/**  */
+modularizeI18nImports?: boolean) => {
     [x: `${string}/?(((\\$*\\w*)?/?)*)`]: {
         transform: `${string}/{{member}}`;
     };

package/compiler/createSwcTransforms.esm.js

@@ -1,13 +1,13 @@
 import { swcCreateTransform } from '@koine/node/swc';
 
-let createSwcTransforms = (e)=>{
-    let { write: o } = e, n = o?.tsconfig ? o.tsconfig.alias : "";
+let createSwcTransforms = (e, o)=>{
+    let { write: n } = e, r = n?.tsconfig ? n.tsconfig.alias : "";
     return {
         ...swcCreateTransform({
             path: "@koine/i18n"
         }),
-        ...n ? swcCreateTransform({
-            path: n
+        ...o && r ? swcCreateTransform({
+            path: r
         }) : {}
     };
 };

package/package.json

@@ -5,9 +5,9 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@koine/dom": "2.0.0-beta.203",
-    "@koine/node": "2.0.0-beta.203",
-    "@koine/utils": "2.0.0-beta.203",
+    "@koine/dom": "2.0.0-beta.205",
+    "@koine/node": "2.0.0-beta.205",
+    "@koine/utils": "2.0.0-beta.205",
     "comment-json": "^4.2.4",
     "consola": "^3.2.3",
     "glob": "^11.0.0",
@@ -130,5 +130,5 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.d.ts",
-  "version": "2.0.0-beta.203"
+  "version": "2.0.0-beta.205"
 }