@ankhorage/orchestrator-module-expo-localization 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/orchestrator-module-expo-localization
 
+## 0.1.3
+
+### Patch Changes
+
+- 35a8eab: Generate localization wiring through `@ankh/runtime` renderer config (prop resolver + `setLanguage` action handler) instead of Surface translation context.
+
+## 0.1.2
+
+### Patch Changes
+
+- Refresh the README copy so the published module overview and install usage stay aligned with the current messaging.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -1,78 +1,16 @@
-# @ankhorage/orchestrator-module-expo-localization
+# orchestrator-module-expo-localization
 
-`@ankhorage/orchestrator-module-expo-localization` is the first standalone module extracted for `@ankhorage/orchestrator`. It replaces the old localization plugin contract from `ankhorage4/packages/plugin-kit` with a pure module that only returns supported orchestrator actions.
+Adds localization support to Expo apps.
 
-The repo follows the module-owned template pattern: generated runtime files come from checked-in [`templates/*.tpl`](./templates) assets that the module reads and materializes into orchestrator `write-files` actions.
-
-## What it does
-
-- ensures `i18next`, `react-i18next`, and `expo-localization`
-- writes localization runtime files into `src/plugins/localization`
-- patches `src/app/_layout.tsx` to wrap the generated app shell with `LocalizationPluginProvider`
-- patches `app.config.ts` to register the Expo localization config plugin
-- keeps `ankh.config.json` aligned at `settings.localization`
-
-The module does not implement or depend on executor behavior outside the orchestrator contract. It only emits `ensure-packages`, `write-files`, `patch-text-block`, and `json-set`.
-
-## Install
-
-```sh
-bun add @ankhorage/orchestrator @ankhorage/orchestrator-module-expo-localization
-```
-
-## Usage
-
-```ts
-import { createOrchestrator } from '@ankhorage/orchestrator';
-import { expoLocalizationModule } from '@ankhorage/orchestrator-module-expo-localization';
-
-const orchestrator = createOrchestrator({
-  modules: [expoLocalizationModule],
-  projectRoot: '/absolute/path/to/project',
-});
-
-await orchestrator.installModule('expo-localization', {
-  config: {
-    defaultLocale: 'en',
-    locales: ['en', 'de'],
-    translations: {
-      en: { hello: 'Hello' },
-      de: { hello: 'Hallo' },
-    },
-  },
-});
-```
-
-## Config
+## 🎯 What you get
+- Localization setup instantly
+- No boilerplate
+- Fully reversible
 
+## 📦 Usage
 ```ts
-{
-  defaultLocale?: string;
-  locales?: string[];
-  translations?: Record<string, Record<string, string>>;
-}
+orchestrator.install('expo-localization')
 ```
 
-Defaults:
-
-- `defaultLocale`: `"en"`
-- `locales`: `["en"]`
-- `translations`: `{}`
-
-## Assumptions
-
-- The target app already has a generated `src/app/_layout.tsx`.
-- The target app uses the standard `@/` alias layout generated by the surrounding Ankhorage toolchain.
-
-This package is meant for the newer `@ankhorage/orchestrator` stack and supersedes the old `@ankh/plugin-kit` localization plugin path that is planned for removal.
-
-## Development
-
-```sh
-bun install
-bun run format:check
-bun run lint
-bun run test
-bun run build
-bun run knip
-```
+## 🧠 Why this exists
+Standardizes localization setup across apps.

package/dist/templateFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templateFiles.d.ts","sourceRoot":"","sources":["../src/templateFiles.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AASpE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD,GAAG,oBAAoB,EAAE,CAoCzB"}
+{"version":3,"file":"templateFiles.d.ts","sourceRoot":"","sources":["../src/templateFiles.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AASpE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD,GAAG,oBAAoB,EAAE,CAyCzB"}

package/dist/templateFiles.js

@@ -22,6 +22,11 @@ export function buildLocalizationWriteFiles(args) {
             content: readTemplate('useT.ts.tpl'),
             overwrite: true,
         },
+        {
+            path: 'src/plugins/localization/runtimeLocalization.ts',
+            content: readTemplate('runtimeLocalization.ts.tpl'),
+            overwrite: true,
+        },
         {
             path: 'src/plugins/localization/LocalizationProvider.tsx',
             content: renderTemplate('LocalizationProvider.tsx.tpl', {

package/dist/templateFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"templateFiles.js","sourceRoot":"","sources":["../src/templateFiles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"templateFiles.js","sourceRoot":"","sources":["../src/templateFiles.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,19 @@
 {
+  "license": "MIT",
   "name": "@ankhorage/orchestrator-module-expo-localization",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Expo localization module for @ankhorage/orchestrator.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "homepage": "https://github.com/ankhorage/orchestrator-module-expo-localization#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/orchestrator-module-expo-localization/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/orchestrator-module-expo-localization.git"
+  },
   "sideEffects": false,
   "files": [
     "dist",
@@ -28,22 +37,22 @@
     "knip": "knip",
     "test": "bun test",
     "changeset": "changeset",
-    "changeset:version": "changeset version"
+    "version-packages": "changeset version"
   },
   "dependencies": {
-    "@ankhorage/orchestrator": "^0.1.1"
+    "@ankhorage/orchestrator": "^0.2.1"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.0.0",
-    "@changesets/cli": "^2.30.0",
-    "@types/bun": "^1.3.11",
-    "@types/node": "^25.2.3",
-    "eslint": "^10.2.0",
-    "knip": "^5.83.1",
-    "prettier": "^3.8.1",
+    "@ankhorage/devtools": "^1.0.1",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^25.6.0",
+    "eslint": "^10.3.0",
+    "knip": "^5.88.1",
+    "prettier": "^3.8.3",
     "typescript": "^5.9.3"
   },
-  "packageManager": "bun@1.3.11",
+  "packageManager": "bun@1.3.13",
   "publishConfig": {
     "access": "public"
   }

package/templates/LocalizationProvider.tsx.tpl

@@ -1,11 +1,14 @@
 /* generated by @ankhorage/orchestrator-module-expo-localization */
-import React, { useEffect, useState } from "react";
+import { RuntimeRendererConfigProvider } from "@ankh/runtime";
+import React, { useEffect, useMemo, useState } from "react";
 import * as ExpoLocalization from "expo-localization";
 import { useTranslation } from "react-i18next";
 
-import { TranslationProvider } from "@ankhorage/surface";
-
 import { initI18n } from "./i18n";
+import {
+  createLocalizationActionHandlers,
+  createLocalizationNodePropsResolver,
+} from "./runtimeLocalization";
 
 export interface LocalizationPluginConfig {
   defaultLocale?: string;
@@ -45,9 +48,18 @@ __RESOURCE_LINES__
     }
   }, [currentLocale, i18n.language]);
 
+  const runtimeRendererConfig = useMemo(() => {
+    const translate = i18n.isInitialized ? t : (key: string) => key;
+
+    return {
+      resolveNodeProps: createLocalizationNodePropsResolver(translate),
+      actionHandlers: createLocalizationActionHandlers(i18n),
+    };
+  }, [i18n, i18n.isInitialized, i18n.language, t]);
+
   return (
-    <TranslationProvider t={i18n.isInitialized ? t : (key: string) => key} i18n={i18n}>
+    <RuntimeRendererConfigProvider value={runtimeRendererConfig}>
       {children}
-    </TranslationProvider>
+    </RuntimeRendererConfigProvider>
   );
 }

package/templates/runtimeLocalization.ts.tpl

@@ -0,0 +1,106 @@
+/* generated by @ankhorage/orchestrator-module-expo-localization */
+import type { RuntimeActionHandlers, RuntimeNodePropsResolver } from "@ankh/runtime";
+import type { i18n as I18nInstance } from "i18next";
+
+const LOCALIZED_PROP_PAIRS = [
+  ["i18nKey", "text"],
+  ["titleI18nKey", "title"],
+  ["descriptionI18nKey", "description"],
+  ["eyebrowI18nKey", "eyebrow"],
+  ["labelI18nKey", "label"],
+  ["helperTextI18nKey", "helperText"],
+  ["errorTextI18nKey", "errorText"],
+  ["metaI18nKey", "meta"],
+  ["childrenI18nKey", "children"],
+] as const;
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function hasOwnProp(props: Record<string, unknown>, key: string) {
+  return Object.prototype.hasOwnProperty.call(props, key);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function resolveLocalizedPropValue(args: {
+  props: Record<string, unknown>;
+  keyProp: string;
+  targetProp: string;
+  translate: (key: string) => string;
+}): string | undefined {
+  const { props, keyProp, targetProp, translate } = args;
+  const key = props[keyProp];
+
+  if (!isNonEmptyString(key)) {
+    return undefined;
+  }
+
+  const translated = translate(key);
+  if (isNonEmptyString(translated) && translated !== key) {
+    return translated;
+  }
+
+  if (hasOwnProp(props, targetProp)) {
+    return undefined;
+  }
+
+  return key;
+}
+
+function isSetLanguageAction(action: {
+  type: string;
+  payload?: unknown;
+}): action is {
+  type: "setLanguage";
+  payload: { locale: string };
+} {
+  return (
+    action.type === "setLanguage" &&
+    isRecord(action.payload) &&
+    isNonEmptyString(action.payload.locale)
+  );
+}
+
+export function createLocalizationNodePropsResolver(
+  translate: (key: string) => string,
+): RuntimeNodePropsResolver {
+  return ({ props }) => {
+    let resolvedProps: Record<string, unknown> | undefined;
+
+    for (const [keyProp, targetProp] of LOCALIZED_PROP_PAIRS) {
+      const localizedValue = resolveLocalizedPropValue({
+        props,
+        keyProp,
+        targetProp,
+        translate,
+      });
+
+      if (localizedValue === undefined) {
+        continue;
+      }
+
+      resolvedProps ??= { ...props };
+      resolvedProps[targetProp] = localizedValue;
+    }
+
+    return resolvedProps ?? props;
+  };
+}
+
+export function createLocalizationActionHandlers(
+  i18n: Pick<I18nInstance, "changeLanguage">,
+): RuntimeActionHandlers {
+  return {
+    setLanguage: ({ action }) => {
+      if (!isSetLanguageAction(action)) {
+        return;
+      }
+
+      void i18n.changeLanguage(action.payload.locale);
+    },
+  };
+}