Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Internationalization & Localization With PHP (L...

Ben Ramsey
November 03, 2023

Internationalization & Localization With PHP (Longhorn PHP 2023)

What’s today’s date? Is it 07/20/2023 or 20/07/2023? Or maybe it’s 2023/07/20? How many elePHPants do you want to buy? Is it 1,500 or 1.500? Will that be $30,000.00 or 30.000,00 $? We represent dates, times, numbers, and currency in a variety of ways, depending on where we are in the world, and writing software to accommodate these different formats can be scary. It’s worse when you find out you need to put these formatted values inside a translated string like, “Sign up before July 20th, and you’ll get 20% off the regular price of $30,000.” String concatenation and standard placeholders won’t work because different languages and regions follow different rules.

Fortunately, we have tools to make our jobs easier, and in this talk, we’ll take a look at FormatPHP and FormatJS, libraries designed to help with internationalization and localization of web applications. We’ll see how these libraries aid in formatting dates, times, numbers, and currency, as well as messages with plural conditions. We’ll learn how to format messages for translation, and by the end of this talk, you’ll know what a translation management system (TMS) is and how to extract strings from your application to send to your translators.

Ben Ramsey

November 03, 2023
Tweet

More Decks by Ben Ramsey

Other Decks in Programming

Transcript

  1. WELCOME A bit about me • Senior Sta ff Engineer

    at Skillshare • PHP 8.1 and 8.2 release manager • Author of ramsey/uuid, et al. • Creator of skillshare/formatphp (which we’ll discuss) • Working on PECL ecma_intl, a port of ECMA-402 to PHP
  2. “Internationalization and localization,” Wikipedia. “Internationalization is the process of designing

    a software application so that it can be adapted to various languages and regions without engineering changes.”
  3. “Internationalization and localization,” Wikipedia. “Localization is the process of adapting

    internationalized software for a specific region or language by translating text and adding locale-specific components.”
  4. I18N & L10N Internationalization & localization • Localization depends on

    the work of internationalization. • Internationalization is the job of programmers. • Localization is the job of copy writers, marketers, product owners, etc.). • Software that has been internationalized can be localized. • Internationalized means it’s ready to adapt to any place. • Localized means it’s ready to use in a speci fi c place.
  5. LOCALIZATION It’s not just translating words into another language •

    Converting from one language to another • Using the correct time zone • Displaying prices in the user’s currency and formatting foreign currencies • Formatting dates and times and using the proper calendar system • Formatting numbers • Displaying the proper names for regions, currencies, languages, etc.
  6. INTERNATIONALIZATION Facilitates localization • Ensure that strings/content can be extracted

    and translated • Languages may be used across multiple locales, so ensure numbers, dates/ times, currencies, time zones, country names, etc. render properly for those locales, no matter what language is used. • Ensure translators have context to understand how to translate a string. • Ensure strings have placeholders the translators can understand, and account for plural forms.
  7. COMMON PITFALLS Setting up • Imagine a function with the

    following signature: • Takes a message, looks it up in a translation table of some sort, replaces placeholders with the values, and returns the result. • Assume the application sets a locale at some point, for this to work. function translate(string $message, mixed ...$values): string;
  8. COMMON PITFALLS Dates & times echo translate( 'Your reservation is

    confirmed for %s at %s.', date('F j, Y', $time), date('g:i A', $time), );
  9. COMMON PITFALLS Numbers echo translate( "You've cycled %s miles this

    year.", number_format(3328.2591, 2, '.', ','), );
  10. COMMON PITFALLS Message formatting echo translate( 'There are %d item(s)

    in your order.', $itemCount, ); echo translate('Read ') . $bookTitle . translate(' by ') . $authorName . '.';
  11. COMMON PITFALLS Why they are mistakes, or misguided attempts •

    Assumes translation is the only requirement for internationalization. • Assumes number, date, & currency formats are the same across locales. • Assumes country names, month names, etc. are the same across locales. • Assumes all languages follow the same subject-verb-object pattern.
  12. TOOLS OFTEN USED • gettext extension for PHP (via libintl,

    a.k.a. GNU gettext) • Uses PO (portable object) fi les for translations • intl extension for PHP (via libicu) • IMO, both are cumbersome and di ffi cult to use • I’ve not encountered a translation vendor that works with PO fi les
  13. INTRODUCING FormatPHP & FormatJS • FormatJS - formatjs.io - Set

    of JavaScript libraries for use on the client & server (Node.js) • FormatPHP - docs.formatphp.dev - userland PHP library that ports the functionality of FormatJS to PHP • Created by me for Skillshare; we use both FormatJS and FormatPHP • Both based on ICU (International Components for Unicode) • Both follow conventions of and provide poly fi lls for ECMA-402
  14. GOALS FOR FORMAT PHP Why did we create it? •

    Already decided on FormatJS, a well-supported set of internationalization tools used by many in the JavaScript community. • Wanted a set of PHP tools: • As easy to use as FormatJS. • Shared the same/similar APIs with FormatJS (reduce cognitive load). • Allowed us to use the same translation work fl ow and formats.
  15. FEATURES Of FormatPHP & FormatJS • Ability to declare i18n-friendly

    messages (FormatJS, FormatPHP) • Linter that enforces such messages (FormatJS, FormatPHP†) • CLI for extraction & compilation (FormatJS, FormatPHP) • Poly fi lls for ECMA-402 functionality (FormatJS, FormatPHP‡) • Bundler plugin for compiling TypeScript/JavaScript (FormatJS) † Not yet. I’d love to see a PR for a PHP_CodeSni ff er “sni ff ” that provides this functionality. ‡ Sort of. ECMA-402 is a speci fi cation for JavaScript, and FormatPHP provides some of this functionality.
  16. FORMAT PHP intl.php (part 1) use FormatPHP\{Config, FormatPHP, Intl, Message,

    MessageCollection}; $messagesInSpanish = new MessageCollection([ new Message('myMessage', 'Hoy es {ts, date, ::yyyyMMdd}'), ]); $intl = new FormatPHP( config: new Config( locale: new Intl\Locale('es-ES'), defaultLocale: new Intl\Locale('en-US'), ), messages: $messagesInSpanish, );
  17. FORMAT PHP intl.php (part 2) echo $intl->formatMessage([ 'id' => 'myMessage',

    'defaultMessage' => 'Today is {ts, date, ::yyyyMMdd}', ], [ 'ts' => new DateTimeImmutable(), ]) . "\n"; echo $intl->formatNumber(19, new Intl\NumberFormatOptions([ 'style' => 'currency', 'currency' => 'EUR', ])) . "\n";
  18. FORMAT JS intl.mjs (part 1) import {createIntl} from '@formatjs/intl' const

    messagesInSpanish = { myMessage: 'Hoy es {ts, date, ::yyyyMMdd}', } const intl = createIntl({ locale: 'es-ES', defaultLocale: 'en-US', messages: messagesInSpanish, })
  19. FORMAT JS intl.mjs (part 2) console.log(intl.formatMessage({ id: 'myMessage', defaultMessage: 'Today

    is {ts, date, ::yyyyMMdd}', }, { ts: Date.now(), })) console.log(intl.formatNumber(19, { style: 'currency', currency: 'EUR', }))
  20. DATES & TIMES FormatPHP $date = new DateTimeImmutable('now'); echo $intl->formatDate($date);

    // e.g., "03/11/2023" echo $intl->formatTime($date); // e.g., "22:31"
  21. DATES & TIMES FormatPHP echo $intl->formatDate($date, new Intl\DateTimeFormatOptions([ 'day' =>

    'numeric', 'month' => 'short', 'weekday' => 'short', 'year' => 'numeric', ])); // e.g., "vie, 3 nov 2023" echo $intl->formatTime($date, new Intl\DateTimeFormatOptions([ 'timeStyle' => 'full', 'timeZone' => 'America/Chicago', ])); // e.g., "17:31:23 (hora de verano central)"
  22. DATES & TIMES FormatJS const date = Date.now() console.log(intl.formatDate(date)) //

    e.g., "03/11/2023" console.log(intl.formatTime(date)) // e.g., "22:31"
  23. DATES & TIMES FormatJS console.log(intl.formatDate(date, { day: 'numeric', month: 'short',

    weekday: 'short', year: 'numeric', })) // e.g., "vie, 3 nov 2023" console.log(intl.formatTime(date, { timeStyle: 'full', timeZone: 'America/Chicago', })) // e.g., "17:31:23 (hora de verano central)"
  24. NUMBERS FormatPHP $number = -12_345.678; echo $intl->formatNumber($number); // e.g., "-12.345,678"

    echo $intl->formatNumber(1562.25, new Intl\NumberFormatOptions([ 'style' => 'unit', 'unit' => 'kilometer', ])); // e.g., "1562,25 km"
  25. NUMBERS FormatJS const number = -12_345.678; console.log(intl.formatNumber(number)); // e.g., "-12.345,678"

    console.log(intl.formatNumber(1562.25, { style: 'unit', unit: 'kilometer', })) // e.g., "1562,25 km"
  26. CURRENCY FormatPHP echo $intl->formatCurrency(123.0, 'USD'); // e.g., "123,00 US$" echo

    $intl->formatCurrency( value: 123.0, currencyCode: 'USD', options: new Intl\NumberFormatOptions([ 'currencyDisplay' => 'narrowSymbol', 'trailingZeroDisplay' => 'stripIfInteger', ]), ); // e.g., "123 $"
  27. CURRENCY FormatJS console.log(intl.formatNumber(123.0, { style: 'currency', currency: 'USD', })); //

    e.g., "123,00 US$" console.log(intl.formatNumber(123.0, { style: 'currency', currency: 'USD', currencyDisplay: 'narrowSymbol', trailingZeroDisplay: 'stripIfInteger', })) // e.g., "123,00 $"
  28. MESSAGES Notes • FormatPHP & FormatJS support ICU message syntax.

    • Starts out simple and can support very complex statements. • ICU is currently working to update and de fi ne MessageFormat 2. • ECMA-402 is tracking the work of MessageFormat 2 closely. • Unclear how it will a ff ect FormatJS and FormatPHP.
  29. MESSAGES FormatPHP $user = (object) ['name' => 'Bilbo']; echo $intl->formatMessage([

    'id' => 'greeting', 'description' => 'Greets a user after they log in.', 'defaultMessage' => 'Hello, {personName}!', ], [ 'personName' => $user->name, ]);
  30. echo $intl->formatMessage([ 'id' => 'sale', 'description' => 'Explains how far

    people walked for the sale prices.', 'defaultMessage' => <<<'EOD' On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture. EOD, ], [ 'actionDate' => new DateTimeImmutable('now'), 'distance' => 5.358, 'amount' => 150.00123, 'percentage' => 0.25, ]);
  31. echo $intl->formatMessage([ 'id' => 'sale', 'description' => 'Explains how far

    people walked for the sale prices.', 'defaultMessage' => <<<'EOD' On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture. EOD, ], [ 'actionDate' => new DateTimeImmutable('now'), 'distance' => 5.358, 'amount' => 150.00123, 'percentage' => 0.25, ]);
  32. echo $intl->formatMessage([ 'id' => 'sale', 'description' => 'Explains how far

    people walked for the sale prices.', 'defaultMessage' => <<<'EOD' On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture. EOD, ], [ 'actionDate' => new DateTimeImmutable('now'), 'distance' => 5.358, 'amount' => 150.00123, 'percentage' => 0.25, ]);
  33. echo $intl->formatMessage([ 'id' => 'sale', 'description' => 'Explains how far

    people walked for the sale prices.', 'defaultMessage' => <<<'EOD' On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture. EOD, ], [ 'actionDate' => new DateTimeImmutable('now'), 'distance' => 5.358, 'amount' => 150.00123, 'percentage' => 0.25, ]);
  34. echo $intl->formatMessage([ 'id' => 'sale', 'description' => 'Explains how far

    people walked for the sale prices.', 'defaultMessage' => <<<'EOD' On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture. EOD, ], [ 'actionDate' => new DateTimeImmutable('now'), 'distance' => 5.358, 'amount' => 150.00123, 'percentage' => 0.25, ]);
  35. On November 3 at 5:35 PM, they walked 5.4 kilometers

    to pay only EUR 150.00 in the 25% o ff sale on furniture.
  36. $host = (object) ['name' => 'Bilbo', 'gender' => 'male']; $party

    = (object) ['guests' => [(object) ['name' => 'Frodo']]]; echo $intl->formatMessage([ 'id' => 'party', 'description' => 'Tells who is inviting whom to their party.', 'defaultMessage' => <<<'EOD' {hostGender, select, female {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to her party.} =2 {{host} invites {guest} and one other person to her party.} other {{host} invites {guest} and # other people to her party.} }} male {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to his party.} =2 {{host} invites {guest} and one other person to his party.} other {{host} invites {guest} and # other people to his party.} }} other {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to their party.} =2 {{host} invites {guest} and one other person to their party.} other {{host} invites {guest} and # other people to their party.} }} } EOD, ], [ 'hostGender' => $host->gender, 'host' => $host->name, 'numGuests' => count($party->guests), 'guest' => $party->guests[0]->name, ]);
  37. 'defaultMessage' => <<<'EOD' {hostGender, select, female {{numGuests, plural, offset:1 =0

    {{host} does not give a party.} =1 {{host} invites {guest} to her party.} =2 {{host} invites {guest} and one other person to her party.} other {{host} invites {guest} and # other people to her party.} }} male {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to his party.} =2 {{host} invites {guest} and one other person to his party.} other {{host} invites {guest} and # other people to his party.} }} other {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to their party.} =2 {{host} invites {guest} and one other person to their party.} other {{host} invites {guest} and # other people to their party.} }} } EOD,
  38. 'defaultMessage' => <<<'EOD' {hostGender, select, female {{numGuests, plural, offset:1 =0

    {{host} does not give a party.} =1 {{host} invites {guest} to her party.} =2 {{host} invites {guest} and one other person to her party.} other {{host} invites {guest} and # other people to her party.} }} male {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to his party.} =2 {{host} invites {guest} and one other person to his party.} other {{host} invites {guest} and # other people to his party.} }} other {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to their party.} =2 {{host} invites {guest} and one other person to their party.} other {{host} invites {guest} and # other people to their party.} }} } EOD,
  39. 'defaultMessage' => <<<'EOD' {hostGender, select, female {{numGuests, plural, offset:1 =0

    {{host} does not give a party.} =1 {{host} invites {guest} to her party.} =2 {{host} invites {guest} and one other person to her party.} other {{host} invites {guest} and # other people to her party.} }} male {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to his party.} =2 {{host} invites {guest} and one other person to his party.} other {{host} invites {guest} and # other people to his party.} }} other {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to their party.} =2 {{host} invites {guest} and one other person to their party.} other {{host} invites {guest} and # other people to their party.} }} } EOD,
  40. MESSAGES FormatJS const user = {name: 'Bilbo'} console.log(intl.formatMessage({ id: 'greeting',

    description: 'Greets a user after they log in.', defaultMessage: 'Hello, {personName}!', }, { personName: user.name, }))
  41. console.log(intl.formatMessage({ id: 'sale', description: 'Explains how far people walked for

    the sale prices.', defaultMessage: ` On {actionDate, date, ::dMMMM} at {actionDate, time, ::jmm}, they walked {distance, number, ::unit/kilometer unit-width-full-name .#} to pay only {amount, number, ::currency/EUR unit-width-short precision-currency-standard/w} in the {percentage, number, ::percent precision-integer} off sale on furniture.`, }, { actionDate: Date.now(), distance: 5.358, amount: 150.00123, percentage: 0.25, }))
  42. const host = {name: 'Bilbo', gender: 'male'} const party =

    {guests: [{name: 'Frodo'}]} console.log(intl.formatMessage({ id: 'party', description: 'Tells who is inviting whom to their party.', defaultMessage: ` {hostGender, select, female {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to her party.} =2 {{host} invites {guest} and one other person to her party.} other {{host} invites {guest} and # other people to her party.} }} male {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to his party.} =2 {{host} invites {guest} and one other person to his party.} other {{host} invites {guest} and # other people to his party.} }} other {{numGuests, plural, offset:1 =0 {{host} does not give a party.} =1 {{host} invites {guest} to their party.} =2 {{host} invites {guest} and one other person to their party.} other {{host} invites {guest} and # other people to their party.} }} }`, }, { hostGender: host.gender, host: host.name, numGuests: party.guests.length, guest: party.guests[0].name, }))
  43. EXTRACTING STRINGS FormatPHP • Extract all the message strings from

    PHP source fi les: ❯ ./vendor/bin/formatphp extract \ --out-file=locales/en.json \ '**/*.php' \ '**/*.phtml' [notice] Message descriptors extracted and written to locales/en.json
  44. EXTRACTING STRINGS FormatJS • Extract all the message strings from

    JS source fi les: ❯ yarn formatjs extract '**/*.mjs' --out-file locales/en2.json yarn run v1.22.19 $ /path/to/project/node_modules/.bin/formatjs extract '**/*.mjs' --out- file locales/en2.json ✨ Done in 0.59s.
  45. { "greeting": { "defaultMessage": "Hello, {personName}!", "description": "Greets a user

    after they log in." }, "myMessage": { "defaultMessage": "Today is {ts, date, ::yyyyMMdd}" }, "party": { "defaultMessage": "{hostGender, select, female {{numGuests, plural, of "description": "Tells who is inviting whom to their party." }, "sale": { "defaultMessage": "On {actionDate, date, ::dMMMM} at {actionDate, time "description": "Explains how far people walked for the sale prices." } }
  46. EXTRACTING STRINGS Notes • Extract from PHP and JS source

    to two di ff erent locales fi les. • These are your “default” locale strings. • Consider merging these fi les, but be careful when IDs & messages overlap. • Merging isn’t necessary, though. • Send these fi les to your translators.
  47. TMS Translation Management Systems • TMSs are what translators use

    to translate your messages. • FormatPHP and FormatJS support extracting messages into JSON format supported by a wide-range of TMSs. • You can automate the process of sending receiving locale translations. • e.g., CrowdIn supports automatic work fl ows that open GitHub PRs on your feature branches when your default locale fi les have changes.
  48. TMS Translation Management Systems ❯ ./vendor/bin/formatphp extract \ --format=crowdin \

    --out-file=locales/en.json \ '**/*.php' \ '**/*.phtml' ❯ yarn formatjs extract '**/*.mjs' \ --format crowdin \ --out-file locales/en2.json
  49. TMS Translation Management Systems TMS --format Smartling smartling Lingohub simple

    Phrase simple Crowdin crowdin SimpleLocalize simple POEditor simple Localize simple locize simple
  50. LOADING STRINGS FormatPHP use FormatPHP\{Config, FormatPHP, Intl, MessageLoader}; $config =

    new Config(new Intl\Locale('es-419')); $messageLoader = new MessageLoader( // The path to your locale JSON files (i.e., en.json, es.json, etc.). '/path/to/app/locales', $config, ); $intl = new FormatPHP($config, $messageLoader->loadMessages());
  51. TESTING With pseudo-locales Locale Message en-XA ṁẏ ńâṁè íś {name}

    en-XB [!! ṁẏ ńâṁṁ ṁè íííś !!]{name} xx-AC MY NAME IS {name} xx-HA [javascript ]my name is {name} xx-LS my name is {name}SSS SSSSSSSSSSSSSSSSSSSSSS
  52. LOOKING AHEAD • ICU MessageFormat 2 • ECMA-402 - Internationalization

    API Speci fi cation • PHP-FIG: PSR-21 - Common Interfaces and Functionality for Interoperability of Message Translation and Formatting • PECL ecma_intl extension - Ports ECMA-402 to PHP
  53. THANK YOU! Keep in touch     

     ben.ramsey.dev phpc.social/@ramsey github.com/ramsey speakerdeck.com/ramsey www.linkedin.com/in/benramsey [email protected] joind.in/talk/3e1e4 ⭐ ⭐ ⭐
  54. ATTRIBUTION • Fonts • Archivo Black by Omnibus-Type, SIL Open

    Font License, Version 1.1 • DM Mono by Colophon Foundry, SIL Open Font License, Version 1.1 • Playfair Display by Claus Eggers S ø rensen, SIL Open Font License, Version 1.1 • Saira by Omnibus-Type, SIL Open Font License, Version 1.1 • OpenMoji • “winking face” by Emily Jäger, CC BY-SA 4.0 • “weary cat” by Emily Jäger, CC BY-SA 4.0