Download the PHP package wufr/php-language-localizer without Composer
On this page you can find all versions of the php package wufr/php-language-localizer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download wufr/php-language-localizer
More information about wufr/php-language-localizer
Files in wufr/php-language-localizer
Package php-language-localizer
Short Description Translate keys into text values based on set language
License MIT
Informations about the package php-language-localizer
PHP Language Localizer
A small, dependency-free PHP library for translating and localizing applications: plain PHP locale files, parameter replacement with HTML escaping, CLDR plural rules, gender variants, fallback languages and layered locale directories.
Features
- Plain PHP locale files organized in any folder hierarchy, loaded once per request
- Parameter replacement with HTML escaping by default and explicit opt-outs for trusted markup
- Pluralization with Unicode CLDR categories (
one,few,many, …) for 60+ languages, or simple numeric thresholds - Gender variants, also combined with plurals
- Number and date formatting per locale (with
ext-intl) - Fallback languages and layered locale directories (override single keys of a base set)
- Safe by design: file and language names are validated, so user input can never load files outside the locale directories
- Configurable handling of missing translations: return the key, log it or throw
Installation
Requirements: PHP 8.1 or higher. ext-intl is optional and only used for locale-aware number and date placeholders.
Upgrading from 1.x? See UPGRADE.md.
Basic Usage
Setters are chainable:
Locale files
A locale file returns an array (or assigns it to $l, the format used by 1.x):
Locale files are PHP code and are fully trusted: only load files you ship yourself. Each file runs in an isolated scope and is loaded once per Translator instance.
Names. A file name is one or more segments separated by /, each made of letters, digits, _, - and . (not starting with a dot). A language is a directory name made of letters, digits, _ and -. Any other name, for example one containing .., \ or an absolute path, never touches the file system and is reported as a missing translation. This makes it safe to pass a language chosen by the visitor, although checking it against the languages you support is still the better choice.
Parameters
All placeholders are replaced in a single pass, so a value that contains {something} is never expanded again. A placeholder without a matching parameter is left as it is.
Values can be strings, numbers, null, bool, enums and Stringable objects. Other types (arrays, plain objects) trigger an E_USER_WARNING and render as an empty string.
Escaping
Parameter values are HTML-escaped by default, because translations usually end up in HTML and values often come from users. The translation text itself is trusted and may contain markup:
To insert trusted markup without escaping, pick the narrowest option:
Never mark user input as raw.
Numbers and dates
With ext-intl installed, typed placeholders format values for the current language:
Date values may be a DateTimeInterface, a Unix timestamp or a date string. Without ext-intl numbers are printed as plain digits and dates as Y-m-d, H:i or Y-m-d H:i.
Pluralization
Pass the number as _counter. It is also available as the {count} placeholder unless you pass count yourself.
CLDR plural categories (recommended)
Use the CLDR plural categories of the language: zero, one, two, few, many and other. The library knows the rules of 60+ languages, including the Slavic ones where 22 and 25 need different forms, and falls back to other when a category is not defined.
Fractions follow CLDR too: 1.5 is many in Czech and other in English. Visible decimals count, so pass '1.0' as a string to get "1.0 items" in English, while the integer 1 gives "1 item".
Languages without a built-in rule use the English one (one for exactly 1). Add or replace a rule with:
Numeric thresholds
Without category keys, integer keys are thresholds: the variant with the highest key that is less than or equal to the counter wins. The order of the keys does not matter, and a counter below every key uses the lowest one.
Thresholds are enough for languages like English or Czech with integer counts. Use categories for languages with more complex rules.
Gender
_gender accepts a Gender case (or any backed enum) or a string key; the keys are not limited to the four Gender values.
Gender and plural variants can be combined. The gender is selected first:
Fallback languages
When the current language lacks a file or a key, the fallback languages are tried in order:
Plural rules and number formats follow the language the text was found in.
Layered locale directories
Pass several directories, highest priority first. Each locale file is merged across every directory that has it, so the first directory can override single keys and leave the rest of the file to the others:
Missing translations
A missing file, key or variant never throws and never breaks the page. By default the translator returns the file.key identifier (escaped), for example common/general.welcome.
Set a handler to log, show something else or throw:
MissingTranslation has the reason (a MissingReason case: FileNotFound, KeyNotFound, InvalidName, SelectorMissing, VariantNotFound, InvalidCounter or InvalidValue), file, key, language and an optional detail. The handler's return value is output as it is, so escape anything you build from these values.
Check for a key without triggering the handler:
API Reference
wUFr\Translator
Reserved parameters: _counter (plural number), _gender (gender key or enum) and _raw (true or a list of parameter names to insert without escaping).
Translator implements wUFr\Localizer\TranslatorInterface (locale() and has()), which is the type to depend on in your own code.
wUFr\Gender
getPronoun(), getPossessivePronoun() and getObjectPronoun() still exist but are deprecated: they return English words only. Put pronouns into your locale files as gender variants instead.
Security
See SECURITY.md for what the library guarantees and how to report a vulnerability.
Contributing
Create a new branch from the release-candidate branch and submit a pull request. Run the checks before pushing:
Commit messages follow Conventional Commits, which drive the automatic releases.
License
This project is licensed under the MIT License - see the LICENSE.md file for details.