Docs UI Examples Benchmarks Showcase

Languages

A MyPHP app says its messages in the language of the people who use it. Its messages live in catalogs, a JSON file per language, from which myphp dev, myphp build and myphp generate write a PHP class with a typed method per message, which says it in the language the app shows, with the plural forms of that language. The whole app shows one language: its own messages, MyPHP's controls and menus, and its pages if it has any.

{
  "filesSelected": "{count, plural, =0 {No files selected} one {# file selected} other {# files selected}}"
}
Text(verbatim: Locales::filesSelected(count($app->selected))); // "3 files selected"

MyPHP\I18n underneath formats numbers and dates with the data of the Unicode CLDR (through ext-intl where it is installed), and an app with a frontend gets the same messages as a TypeScript module (In pages).

Catalogs

Turn the catalogs on in the configuration, in myphp.json:

{
  "i18n": { "dir": "locales", "source": "en" }
}

dir (default locales) holds a catalog per language, named after its BCP 47 tag: en.json, de.json, pt-BR.json, zh-Hans.json, zh-Hant.json. source (default en) is the language the app is written in: its catalog has every message, and the others fall back to it. The languages the app ships are the files of dir; an app without catalogs ships English.

A catalog is an object of messages, in the ARB format, whose keys name them. The source language's also describes them, under the key with an @, for the translators and the generated code:

{
  "@@locale": "en",
  "filesSelected": "{count, plural, =0 {No files selected} one {# file selected} other {# files selected}}",
  "@filesSelected": {
    "description": "The status bar, while files are selected.",
    "placeholders": {
      "count": { "type": "int", "example": "3" }
    }
  },
  "greeting": "Hello, {name}!"
}
{
  "@@locale": "de",
  "filesSelected": "{count, plural, =0 {Keine Dateien ausgewählt} one {# Datei ausgewählt} other {# Dateien ausgewählt}}",
  "greeting": "Hallo, {name}!"
}

A key is a letter, then letters, digits and _; the methods of a key are named after it. A placeholder's type is String, int, double, num, DateTime or Object, which makes the type of the methods' parameter (string, int, float, int|float, DateTimeInterface and mixed in PHP; string, number, Date and unknown in TypeScript). Without one, an argument counted by plural, selectordinal or number is an int, a date or time argument a DateTime, and any other a String. @@locale is optional, and must name the file's language.

Keys are flat: a dot in a key is for MyPHP's own strings (myphp.undo). Name related messages with a common start, as sidebarTitle, sidebarEmpty and sidebarNewNote, which sort together in the catalogs and in your editor's completion.

Messages

Messages are written in ICU MessageFormat, the format of ARB files, of Android and of Format.JS:

MessageSays
Hello, {name}!the value of name in its place
{count, plural, one {# file} other {# files}}the case of the plural category of count in the message's language; # is the number
{count, plural, =0 {No files} one {# file} other {# files}}=0 is for exactly 0, before the categories
{n, plural, offset:1 =0 {Nobody} =1 {{host}} one {{host} and # other} other {{host} and # others}}with offset:1, the categories and # count n - 1
{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}the case of the ordinal category: 1st, 22nd, 103rd, 11th
{gender, select, female {She} male {He} other {They}} replied.the case named after the value, else other
{price, number}, {ratio, number, percent}, {n, number, integer}a number in the language's way (1,234.5; 1.234,5; 12,34,567)
{price, number, ::.00}, {n, number, ::group-off}a number with exactly two fraction digits, or without separators of thousands
{day, date, short}, {day, time, short}a date, or a time, in a style: short, medium, long or full
{day, date, ::yMMMd}a date of the fields of a skeleton of CLDR, in the language's order (Jan 5, 2026; 5. Jan. 2026)

Cases nest, and every plural, selectordinal and select has an other case. The plural categories are those of the Unicode CLDR for the message's language: one and other in English, only other in Chinese and Japanese, one, few, many and other in Russian, six in Arabic. Write the ones the language has; other is required.

An apostrophe quotes the next brace, or # in a plural case: '{' says {, '{name}' says {name}, and two apostrophes say one. Any other apostrophe is just one, so don't needs no quoting.

MyPHP\Message parses and formats a message by itself: Message::parse($source)->format('de', ['count' => 3]).

In the declarative views

As SwiftUI's String Catalog: the text a view shows is the key of its translation, so Text('Submit'), Button('Save', …), a Toggle's, a Picker's or a Section's title, a field's prompt, navigationTitle(), help() and an alert's text are looked up in the app's catalogs and said in the language the app shows; a text no catalog has is shown as it is. Their keys are the text itself, which needs no method of its own:

{ "Profile": "个人资料", "Submit": "提交", "Hello, {name}!": "你好,{name}!",
  "{n, plural, one {# file} other {# files}}": "{n, plural, other {# 个文件}}" }
Text('Hello, {name}!', name: $this->name)        // its ICU placeholders, as SwiftUI's "Hello, \(name)!"
Text(verbatim: $note->title)                      // what the user wrote: neither translated nor read as Markdown
VStack()( … )->environment(locale: 'zh-Hans')     // the views inside in Chinese, as SwiftUI's environment(\.locale, …)

Identifier keys (filesSelected) keep their typed methods (below); a key that is not one is a text's, which only an app's catalog has. A text that holds what the user wrote is Text(verbatim:), so that a word of theirs that happens to be a key is not translated. examples/form switches between English, Chinese and Spanish this way.

In PHP

myphp dev, myphp build and myphp generate write the accessors into the catalogs' directory: a class named after the directory (Locales for locales), which registers the catalogs as it is required. Each message is a static method saying it in the language the app shows, and in() says it in another:

require __DIR__ . '/locales/Locales.php';

$status = Locales::filesSelected(3);           // the app's language
$hello = Locales::in('de')->greeting('Welt');  // "Hallo, Welt!"

When the language changes

The accessors read App::locale() each time they are called, so a view of native UI, which builds every frame, shows the new language at once. Text made once, as a window's title, is made again when the language changes: App::onLocaleChanged() hears it, and App::relabelMenus() installs the menu bar again, its roles' labels in the new language.

The language the app shows

App::locale() is the language the app shows: the first of the user's preferred languages (App::preferredLanguages(), as the system lists them) that the app is written in, else the source language. An app with a setting of its own sets it with App::setLocale($tag), '' for the system's again, and App::setLanguages(...) says which languages the app ships when it has no catalogs. App::languages() lists them.

Native UI

A view reads the language with $c->locale(), and MyPHP's own strings in it with $c->texts(). The controls of native UI say their names, labels and menus in the app's language (MyPHP's own strings), and a window of a language written right to left is laid out right to left.

Regional formats

The regional formats are the user's, which may not be the language's: a German reading the app in English may want 24-hour times and Monday first. App::region() (and $c->region() in a view) returns a Region: its locale, firstWeekday and hourCycle, and App::onRegionChanged() hears them change. $c->formats() puts them together with the app's language, for what a view writes.

Formatting numbers and dates

I18n::formatNumber('de', 1234.5);                                    // "1.234,5"
I18n::formatNumber('en', 0.25, new NumberOptions(percent: true));    // "25%"
I18n::formatDate('ja', new DateTimeImmutable('2026-01-05'), new DateOptions(date: Style::Medium));
I18n::months('fr');      // the names of the months
I18n::weekdays('en');    // of the weekdays, Sunday first
I18n::autonym('zh-Hant'); // the language's name in itself: "中文(繁體)"

NumberOptions (percent, integer, fraction digits, noGrouping) and DateOptions (a date and a time Style, or a skeleton) take what messages take. I18n::firstWeekday() and hourCycle() give a language's defaults, direction() its direction, and match($preferred, $supported) picks the best of the languages an app has for the user's.

MyPHP's own strings

MyPHP's controls, its code editor and the roles of its menus say their words in English, Chinese (simplified and traditional) and Japanese (src/l10n). An app changes them, or translates them to its other languages, with keys myphp.<key> in its own catalogs:

{
  "@@locale": "de",
  "myphp.cancel": "Abbrechen",
  "myphp.search": "Suchen"
}

L10n::in($locale)->get($key) says one of them, as $c->texts() does in a view.

Which message

A message is said in the app's language when its catalog has it, else in the languages it falls back to (de-AT to de, zh-Hant-HK to zh-Hant), else in the source language. Numbers and dates in a message follow its language.

Checking the catalogs

myphp i18n check reads the catalogs and reports what is wrong: messages that do not parse, arguments a translation uses that the source message has not, plural cases a language lacks or has not, and keys missing from a translation, which then says the source language's. myphp dev and myphp build report the same.

Trying a language

myphp dev -lang de runs the app in a language whatever the system's; the pseudo locales en-XA (accented and longer text) and ar-XB (right to left) show what is not translated and what does not fit, before any translation.