Languages and formats

i18n translates your messages and formats money, dates and numbers for each locale, with right-to-left and Indian scripts working from the start. Reach for it on the first string a user reads.

i18n:
  driver: files
  locales: [en-IN, hi-IN, ta-IN]

import { t, i18n } from "mainsdk";

const title = t("orders.count", { count: orders.length });
const total = i18n.format.money(125000, "INR");   // ₹1,25,000 in en-IN

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

describe("heading", () => {
  it("pluralises the order count in Hindi and English", () => {
    const app = createTestApp({ main: "./main.yaml", dir: process.cwd() });
    assert.equal(app.i18n.t("orders.count", { count: 1 }), "1 order");
    assert.equal(app.i18n.with("hi-IN", () => app.i18n.t("orders.count", { count: 3 })), "3 ऑर्डर");
  });
});

i18n:
  driver: files

Quick start

i18n:
  driver: files
  locales: [en-IN, hi-IN, ta-IN]

orders.count: "{count, plural, one {# order} other {# orders}}"

import { i18n, t } from "mainsdk";

export function heading(orders: unknown[]) {
  const title = t("orders.count", { count: orders.length });
  const total = i18n.format.money(125000, "INR");   // ₹1,25,000.00 in en-IN
  return `${title} · ${total}`;
}

Configuration

i18n:
  driver: files                    # files | tolgee | crowdin | lokalise | ai-draft
  default: en-IN
  locales: [en-IN, hi-IN, ta-IN]   # the locales you ship
  required: [en-IN, hi-IN]         # check fails on a missing key in these
  negotiate: [choice, account, header]   # never ip
  cookie: locale                   # cookie that holds the reader's explicit choice
  dir: locales                     # folder of locale files

An unknown key under i18n stops the app at load with MAIN-CONFIG-0003, naming the key.

Locale files live in locales/<locale>.yaml and fall back along a chain: hi-IN, then hi, then en-IN, then en. Templates follow the same chain. A market overlay can set its own locales; see main.yaml.

i18n:
  locales: [en-IN, hi-IN, ta-IN]

What you get

Messages use Unicode MessageFormat 2, and ICU MessageFormat strings still load. Formats come from Unicode CLDR through the runtime's Intl, so ₹1,25,000 shows correctly in India and MainSDK ships no locale data.

Examples

Right-to-left layout

import { i18n } from "mainsdk";

export function htmlAttributes() {
  return { lang: i18n.locale(), dir: i18n.dir() };
}

Spread the result on <html> in your root layout: <html {...htmlAttributes()}>.

Negotiate the locale per request

i18n.handle() negotiates the locale from the choice cookie, the account and Accept-Language, then runs your handler in it. t() and i18n.format.* inside use that locale.

import { auth, i18n, t } from "mainsdk";

export async function GET(req: Request) {
  const session = await auth.require(req);
  return i18n.handle(req, () => Response.json({ title: t("orders.count", { count: 2 }) }), {
    user: { id: session.user },
  });
}

Use i18n.negotiate(req, { user }) to get only the locale, and i18n.with("hi-IN", fn) to run code in a locale you choose, such as an email in the recipient's language.

Dates and other formats in the reader's locale

import { i18n } from "mainsdk";

export function shippedOn(date: Date) {
  return i18n.format.date(date);   // "27 Oct 2026" in en-IN
}

i18n.format also has number(), money(), list() and relative(): list(["a", "b", "c"]) gives "a, b and c" and number(1234567.5) gives 12,34,567.5 in en-IN.

Formats in PDF templates

pdf templates format money, numbers and dates through the same locale formats, for example {{total | money:INR}}. Locale-specific template files (order.shipped.hi-IN.yaml) for email and notify are planned.

Reference

Everything below is exported from mainsdk and is pure TypeScript. Most apps use only t() and the i18n instance; the rest is for tools, tests and custom drivers.

Formats

Each takes the active locale from i18n.locale().

formatsFor(locale) returns the same formats for one locale, localeSupported(locale) is true when the runtime's Intl can format it, and localeDir(locale) returns ltr or rtl.

Build the interface

Messages

Locale negotiation

Files, drafts and providers

Interchange and pseudo-locales

Errors and checks

• A key missing from a required locale fails mainsdk check with MAIN-I18N-0001, and a message that does not parse or whose variables differ from the default locale's with MAIN-I18N-0003.
• A locale the target runtime's Intl can't format is MAIN-I18N-0002; negotiate listing ip is MAIN-I18N-0008.
• review: none on an AI-draft locale is warned with MAIN-I18N-0006.
• At run time a fallback logs MAIN-I18N-0004, a value t() was not given logs MAIN-I18N-0005, and a key missing everywhere logs MAIN-I18N-0009; production returns an empty string, never the key.
• mainsdk i18n pseudo writes long, accented and right-to-left pseudo-locales to catch layout breaks before any translator sees them.

Every code is in check codes. See The check.

Swapping drivers

i18n:
  driver: tolgee   # was files

Your t() and i18n.* calls stay the same. The provider drivers pull messages from Tolgee, Crowdin or Lokalise and keep the last good set when the provider is down.

With ai-draft, mainsdk i18n draft [--locale hi-IN] asks the ai interface for the messages a locale lacks, follows your glossary, and holds each draft as pending in locales/.drafts/. The call goes through every ai guard. A draft reaches users only after a person approves it:

import { i18n } from "mainsdk";

const { items } = await i18n.drafts.list({ locale: "hi-IN" });
for (const d of items.filter((x) => x.status === "pending")) {
  await i18n.drafts.approve(d.id);                          // or approve(d.id, { text: "edited" })
  // await i18n.drafts.reject(d.id, { reason: "wrong term" });
}

An agent or service that tries to approve or reject gets MAIN-I18N-0007; the refusal is audited.

Strings move between drivers and translators' tools with mainsdk i18n export --format <f> and mainsdk i18n import <file>, where the format is xliff, xcstrings, android or icu-json. mainsdk i18n extract lists the keys your code uses and the ones the default locale lacks.

Testing

Point the test app at your main.yaml and project folder; it reads locales/ and runs on in-memory drivers.

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

describe("heading", () => {
  it("pluralises the order count in Hindi and English", () => {
    const app = createTestApp({ main: "./main.yaml", dir: process.cwd() });
    assert.equal(app.i18n.t("orders.count", { count: 1 }), "1 order");
    assert.equal(app.i18n.with("hi-IN", () => app.i18n.t("orders.count", { count: 3 })), "3 ऑर्डर");
  });
});

Security and privacy

• The locale comes from the user's choice first, then their account, then the browser. It is never guessed from IP alone.
• AI drafts go through the ai interface with redaction, limits and audit, and are held for a person's review.
• Android values-hi/ and iOS .xcstrings files generated from the same locales with the Expo adapter are planned for phase 3.

FAQ

Do Indian scripts render correctly? In the browser, yes: shaping is the browser's job. In PDFs, the built-in renderer doesn't shape Devanagari or Tamil, so use the gotenberg or docraptor driver; check reports MAIN-DOC-0011 otherwise.

What happens if a string is missing at run time? The check fails before merge, so it should not reach users. At run time the fallback chain applies, and the first miss for a key is logged once.

Next

• Translate your app
• PDF documents
• main.yaml