i18n

App copy lives in message catalogs — greetings, plurals, and status lines you format inside a Flow with fx.t. Configure supported locales once in oke.config.ts; the request's Accept-Language picks the active tag.

Quick start

i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },

import { defineMessages, defineLocale } from "okengine";

export const en = defineMessages({
  greeting: "Hello, {name}",
  items: "{count, plural, one {# item} other {# items}}",
  errors: { notFound: "Not found" },
});
defineLocale("en", en);

declare module "okengine" {
  interface Register {
    messages: typeof en;
  }
}

import { defineLocale, type MessagesFor } from "okengine";
import { en } from "./en";

defineLocale("ar", {
  greeting: "مرحباً، {name}",
  items: "{count, plural, zero {لا عناصر} one {عنصر واحد} other {# عناصر}}",
  errors: { notFound: "غير موجود" },
} satisfies MessagesFor<typeof en>);

do: async (input, fx) => {
  return {
    text: fx.t("greeting", { name: input.name }),
    countLabel: fx.t("items", { count: input.count }),
    locale: fx.locale,
  };
},

Config (i18n)

Matching: exact tag → language subtag (ar-SA → ar) → default.

fx.t and fx.locale

Nested trees flatten to dot keys (errors.notFound). App overlays win over built-in keys for the same locale.

ICU MessageFormat

fx.t formats catalog strings with ICU MessageFormat (FormatJS). The active locale drives plural/select rules — English one/other vs Arabic zero/two/few/many on the same key.

# inside a plural/ordinal branch is the numeric argument. Always include an other (or =N) branch — ICU requires a fallback.

Interpolation

// catalog: "Hello, {name}"
fx.t("greeting", { name: "Ada" }); // → "Hello, Ada"

Values may be string, number, boolean, Date, null / undefined, or a rich-text function (below). Missing args leave the source string unformatted.

Plurals (cardinal)

// en: "{count, plural, =0 {no items} one {# item} other {# items}}"
fx.t("items", { count: 0 }); // → "no items"
fx.t("items", { count: 1 }); // → "1 item"
fx.t("items", { count: 5 }); // → "5 items"

Arabic cardinals

Arabic (ar) uses six CLDR cardinal categories. FormatJS picks the branch from fx.locale — an English one/other skeleton on ar misfires for dual, paucal, and hundreds.

Write every branch on the Arabic catalog (starter items key):

// ar catalog
items: "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصراً} other {# عنصر}}";

// fx.locale === "ar"
fx.t("items", { count: 0 }); // → "لا عناصر"      (zero)
fx.t("items", { count: 1 }); // → "عنصر واحد"     (one)
fx.t("items", { count: 2 }); // → "عنصران"        (two)
fx.t("items", { count: 5 }); // → "5 عناصر"       (few)
fx.t("items", { count: 11 }); // → "11 عنصراً"     (many)
fx.t("items", { count: 100 }); // → "100 عنصر"      (other)
fx.t("items", { count: 103 }); // → "103 عناصر"     (few — 103 % 100 = 3)

Consequence: copy the six-way shape for Arabic noun counts; do not reuse an English one/other skeleton. # still inserts the number inside a branch.

Ordinals (selectordinal)

// "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!"
fx.t("place", { place: 1 }); // → "You finished 1st!"
fx.t("place", { place: 11 }); // → "You finished 11th!"

Select (enums)

// "{status, select, online {Online} offline {Offline} other {Unknown}}"
fx.t("status", { status: "online" }); // → "Online"
fx.t("status", { status: "away" }); // → "Unknown"

Rich-text tags

Tags in the message become function values. The function receives the formatted inner chunks and returns a string (HTML, Markdown, plain wrappers):

// catalog: "Read <docs>the docs</docs>"
fx.t("cta", {
  docs: (chunks) => `<a href="/docs">${chunks.join("")}</a>`,
});
// → 'Read <a href="/docs">the docs</a>'

Escaping

Malformed ICU falls back to the raw catalog string (no throw from fx.t).

Typed keys

Augment Register with your English tree so fx.t autocompletes and rejects typos. Keep other locales aligned with satisfies MessagesFor<typeof en>.

Built-in failure catalogs

English and Arabic ship for typed failures and OKE codes — no app registration required:

Override any key with defineLocale. Pass fail(code, data, { message }) (or fx.t(...)) when you need a one-off string. Custom app codes stay message-less until registered. Full tables: Errors.

Channel catalogs are separate

fx.send templates use {{field}} bodies and their own locales list — not ICU. Omit locale / profileLocale / acceptLanguage on fx.send and the send uses fx.locale. Details: Channel.

Troubleshooting

Learn more

• fx — full fx surface including fx.t / fx.locale
• Errors — localized failure messages and OKE codes
• Configuration — i18n block next to drivers
• Channel — {{field}} templates and locale chain
• Flow — envelope shape with optional error.message

Next