Download the PHP package bermudaphp/polyglot without Composer

Polyglot

Polyglot is a powerful, flexible internationalization (i18n) and localization (l10n) library for PHP 8.4+ applications with support for ICU message formatting, pluralization, caching, and more.

Read documentation in Russian (Документация на русском)

Table of Contents

• Installation
• Basic Usage
• Key Concepts
• Creating a Translator
• Locales
• Translation Files
• Pluralization
• ICU Message Format
  • Parameter Substitution
  • Number Formatting
  • Date Formatting
  • Plural Formatting
  • Select Formatting
  • Nested Formatting
• Message Builders
  • ICU Message Builder
  • Plural Builder
  • Select Builder
• Caching
• Locale Detection
• PSR-15 Middleware
• License

Installation

Basic Usage

Key Concepts

Polyglot uses several core concepts:

• Locale: Identifies a specific language and region (e.g., 'en_US', 'fr_FR')
• Domain: Groups related translations (e.g., 'messages', 'errors', 'admin')
• Translation Key: Unique identifier for a translatable string
• Fallback Locale: Used when a translation is missing in the primary locale
• Plurality: Different forms of words based on quantity (e.g., "1 item" vs "5 items")
• ICU Format: International Components for Unicode message format for complex translations

Creating a Translator

The simplest way to create a translator is using the factory:

For more control, you can create components manually:

Locales

Polyglot provides multiple ways to handle locale codes:

1. As simple strings ('en', 'en_US', 'fr_FR')
2. Using the LocaleEnum typed enum
3. Using the Locale value object

LocaleEnum

Locale Value Object

Translation Files

Polyglot supports multiple formats for translation files:

PHP Array Files

JSON Files

Accessing Nested Keys

Nested keys can be accessed using dot notation:

Pluralization

Polyglot provides robust support for pluralization based on the CLDR (Common Locale Data Repository) rules:

ICU Message Format

Polyglot supports the ICU (International Components for Unicode) message format, a powerful standard for handling translations with variables, pluralization, and more.

Parameter Substitution

Number Formatting

Date Formatting

Plural Formatting

Select Formatting

Nested Formatting

Message Builders

Polyglot provides a set of builders to programmatically create ICU message templates.

ICU Message Builder

Plural Builder

Select Builder

Caching

Polyglot supports caching of loaded translations to improve performance:

Also included is an InMemoryCache for simple use cases:

Locale Detection

Polyglot can automatically detect the user's preferred locale:

PSR-15 Middleware

Polyglot includes a PSR-15 middleware for detecting the locale from HTTP requests:

The middleware:

1. Detects the locale from the request
2. Sets it in the I18n instance
3. Adds the locale as a request attribute
4. Passes control to the next middleware

License

The Polyglot library is open-sourced software licensed under the MIT license.