From 1db0d5042d55479d0ec01bdc1ae5c69e0d65bdb0 Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Mon, 6 Jul 2026 10:58:49 +0000 Subject: [PATCH 1/2] Docs: move documentation to README. Co-authored-by: Felix --- .docs/README.md | 358 ------------------------------------------- README.md | 393 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 372 insertions(+), 379 deletions(-) delete mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md deleted file mode 100644 index 64b708dc..00000000 --- a/.docs/README.md +++ /dev/null @@ -1,358 +0,0 @@ -# Translation - -## Content -- [Setup](README.md#setup) -- [Configuration](README.md#configuration) - - [Locale resolvers](#locale-resolvers) -- [Examples](README.md#examples) - - [Presenter](#presenter) - - [Model](#model) - - [Latte](#latte) - - [Neon](#neon) - - [Parameters in messages](#parameters-in-messages) -- [Loaders](#loaders) - - [File loaders](#file-loaders) - - [Database loaders](#database-loaders) - - [Doctrine](#doctrine) - - [Nette Database](#nette-database) -- [Features](#features) - - [Wrappers](#wrappers) - - [TranslationProviderInterface](#translationproviderinterface) - -## Setup - -Require package: - -```bash -composer require contributte/translation -``` - -Register extension: - -```neon -extensions: - translation: Contributte\Translation\DI\TranslationExtension -``` - -## Configuration - -Basic configuration: - -```neon -translation: - locales: - whitelist: [en, cs, sk] - default: en - fallback: [en] - dirs: - - %appDir%/lang - returnOriginalMessage: true # to not translate undefined messages, default is true -``` -Note: The `fallback` configuration values should always reflect the **locale code** used in the file you wish to _fallback_ to (e.g. `en_US` for `messages.en_US.neon`, or `en` for `messages.en.neon`). - -### Locale resolvers - -This configuration instructs the extension how to resolve the locale and the order in which it will do so: - -```neon -translation: - localeResolvers: - - Contributte\Translation\LocalesResolvers\Router -``` - -Available resolvers: - -- Contributte\Translation\LocalesResolvers\Router -- Contributte\Translation\LocalesResolvers\Header (HTTP header) -- Contributte\Translation\LocalesResolvers\Parameter (Get parameter) -- Contributte\Translation\LocalesResolvers\Session - -By default the `Router`, `Parameter` and `Session` resolvers expect the name of the parameter/key to be `locale`. - -## Examples - -### Presenter - -```php -translatorSessionResolver->setLocale($locale); - $this->redirect('this'); - } - - - public function renderDefault(): void - { - $this->translator->translate('domain.message'); - $prefixedTranslator = $this->translator->createPrefixedTranslator('domain'); - $prefixedTranslator->translate('message'); - } - -} -``` - -### Model - -```php -translator = $translator; - } - -} -``` - -### Latte - -How to use on frontend. - -```latte -{_domain.message} -{_domain.message, $count} -{_domain.message, [name => "Ales"]} - -{translator domain} - {_message} - {_message, $count} - {_message, [name => "Ales"]} -{/translator} - -{var $myMessage = 'domain.message'} -{$myMessage|translate} -``` - -### Neon - -File name format: - -``` - locale - | - /--\ -messages.en_US.neon -\______/ \__/ - | | - domain extension -``` - -File content format: - -```neon -prefix: - for: "message" # messages.prefix.for -``` - -### Parameters in messages - -Sometimes it is convenient to include a dynamic parameter in the translation - as seen in the Latte examples above. - -Neon: - -```neon -user.name.taken: "Sorry, the username %name% is already taken, please try a different one." -``` - -Latte: - -```latte -{_user.name.taken, [name => "Ales"]} -``` - -Presenter/Model: - -```php -$this->translator->translate('user.name.taken', [name => 'Ales']); -``` - -**Note**: When passing parameters to the translator, the parameter names must not be enclosed in `%` characters. This is done by `Contributte/Translation` automatically. - -## Loaders - -By default the extension will look for `.neon` files. - -### File loaders - -```neon -array: Symfony\Component\Translation\Loader\ArrayLoader -csv: Symfony\Component\Translation\Loader\CsvFileLoader -dat: Symfony\Component\Translation\Loader\IcuDatFileLoader -res: Symfony\Component\Translation\Loader\IcuResFileLoader -ini: Symfony\Component\Translation\Loader\IniFileLoader -json: Symfony\Component\Translation\Loader\JsonFileLoader -mo: Symfony\Component\Translation\Loader\MoFileLoader -php: Symfony\Component\Translation\Loader\PhpFileLoader -po: Symfony\Component\Translation\Loader\PoFileLoader -ts: Symfony\Component\Translation\Loader\QtFileLoader -xlf: Symfony\Component\Translation\Loader\XliffFileLoader -yml: Symfony\Component\Translation\Loader\YamlFileLoader -``` - -### Database loaders - -Package includes database loaders for **[Doctrine 2](https://www.doctrine-project.org/)** and **[Nette Database 3](https://doc.nette.org/cs/3.0/database)**. - -#### Doctrine - -You must create a file with specific format in scanned dirs such as **messages.en_US.doctrine**. All parameters are optional, but the file has to exist. - -```neon -table: "My\Entity" # if you specify the entity key, "messages" from file name will be ignored -id: "id" # id column name, default is "id" -locale: "locale" # locale column name, default is "locale" -message: "message" # message column name, default is "message" -``` - -Add loader to translation configuration: - -```neon -translation: - loaders: - doctrine: Contributte\Translation\Loaders\Doctrine -``` - -Entity example: - -```php -addText('mail', 'form.mail.label') - ->setOption('description', new Contributte\Translation\Wrappers\Message('form.mail.description', [...]); -``` - -Or pass the not translatable texts: - -```php -$form->addSelect('country', 'form.country.label') - ->setItems([ - new Contributte\Translation\Wrappers\NotTranslate('Czech republic'), - new Contributte\Translation\Wrappers\NotTranslate('Slovak republic'), - ]); -``` - -### TranslationProviderInterface - -It is possible to pass additional translation resources from your compiler extensions by implementing the `TranslationProviderInterface`. - -```php -use Nette\DI\CompilerExtension; -use Contributte\Translation\DI\TranslationProviderInterface; - -class MyExtension extends CompilerExtension implements TranslationProviderInterface -{ - - public function getTranslationResources(): array - { - return [ - __DIR__ . '/../lang/', - ]; - } - -} -``` diff --git a/README.md b/README.md index 8d6fb31d..cd21e8fc 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,399 @@ ![](https://heatbadger.now.sh/github/readme/contributte/translation/)

- - - - + + + +

- - - - - + + + + +

- Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte +Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

-## Usage +Symfony Translation integration for Nette Framework with locale resolving, Latte helpers, file loaders, and optional database loaders. -To install the latest version of `contributte/translation` use [Composer](https://getcomposer.org). +## Versions + +| State | Version | Branch | PHP | Symfony | +|--------|----------|------------------|--------------|--------------| +| stable | `^2.0.0` | `master` | `^8.0` | `^6.0\|^7.0` | +| stable | `^1.0.0` | `php74_symfony5` | `^7.4\|^8.0` | `^5.0` | + +## Content + +- [Installation](#installation) +- [Configuration](#configuration) + - [Locale resolvers](#locale-resolvers) +- [Examples](#examples) + - [Presenter](#presenter) + - [Model](#model) + - [Latte](#latte) + - [Neon](#neon) + - [Parameters in messages](#parameters-in-messages) +- [Loaders](#loaders) + - [File loaders](#file-loaders) + - [Database loaders](#database-loaders) + - [Doctrine](#doctrine) + - [Nette Database](#nette-database) +- [Features](#features) + - [Wrappers](#wrappers) + - [TranslationProviderInterface](#translationproviderinterface) +- [Development](#development) + +## Installation + +To install latest version of `contributte/translation` use [Composer](https://getcomposer.org). ```bash composer require contributte/translation ``` -## Documentation -For details on how to use this package, check out our [documentation](.docs). +Register extension: -## Versions -| State | Version | Branch | PHP | Symfony | -|--------|----------|------------------|--------------|--------------| -| stable | `^2.0.0` | `master` | `^8.0` | `^6.0\|^7.0` | -| stable | `^1.0.0` | `php74_symfony5` | `^7.4\|^8.0` | `^5.0` | +```neon +extensions: + translation: Contributte\Translation\DI\TranslationExtension +``` + +## Configuration + +Basic configuration: + +```neon +translation: + locales: + whitelist: [en, cs, sk] + default: en + fallback: [en] + dirs: + - %appDir%/lang + returnOriginalMessage: true # to not translate undefined messages, default is true +``` +Note: The `fallback` configuration values should always reflect the **locale code** used in the file you wish to _fallback_ to (e.g. `en_US` for `messages.en_US.neon`, or `en` for `messages.en.neon`). + +### Locale resolvers + +This configuration instructs the extension how to resolve the locale and the order in which it will do so: + +```neon +translation: + localeResolvers: + - Contributte\Translation\LocalesResolvers\Router +``` + +Available resolvers: + +- Contributte\Translation\LocalesResolvers\Router +- Contributte\Translation\LocalesResolvers\Header (HTTP header) +- Contributte\Translation\LocalesResolvers\Parameter (Get parameter) +- Contributte\Translation\LocalesResolvers\Session + +By default the `Router`, `Parameter` and `Session` resolvers expect the name of the parameter/key to be `locale`. + +## Examples + +### Presenter + +```php +translatorSessionResolver->setLocale($locale); + $this->redirect('this'); + } + + + public function renderDefault(): void + { + $this->translator->translate('domain.message'); + $prefixedTranslator = $this->translator->createPrefixedTranslator('domain'); + $prefixedTranslator->translate('message'); + } + +} +``` + +### Model + +```php +translator = $translator; + } + +} +``` + +### Latte + +How to use on frontend. + +```latte +{_domain.message} +{_domain.message, $count} +{_domain.message, [name => "Ales"]} + +{translator domain} + {_message} + {_message, $count} + {_message, [name => "Ales"]} +{/translator} + +{var $myMessage = 'domain.message'} +{$myMessage|translate} +``` + +### Neon + +File name format: + +``` + locale + | + /--\ +messages.en_US.neon +\______/ \__/ + | | + domain extension +``` + +File content format: + +```neon +prefix: + for: "message" # messages.prefix.for +``` + +### Parameters in messages + +Sometimes it is convenient to include a dynamic parameter in the translation - as seen in the Latte examples above. + +Neon: + +```neon +user.name.taken: "Sorry, the username %name% is already taken, please try a different one." +``` + +Latte: + +```latte +{_user.name.taken, [name => "Ales"]} +``` + +Presenter/Model: + +```php +$this->translator->translate('user.name.taken', [name => 'Ales']); +``` + +**Note**: When passing parameters to the translator, the parameter names must not be enclosed in `%` characters. This is done by `Contributte/Translation` automatically. + +## Loaders + +By default the extension will look for `.neon` files. + +### File loaders + +```neon +array: Symfony\Component\Translation\Loader\ArrayLoader +csv: Symfony\Component\Translation\Loader\CsvFileLoader +dat: Symfony\Component\Translation\Loader\IcuDatFileLoader +res: Symfony\Component\Translation\Loader\IcuResFileLoader +ini: Symfony\Component\Translation\Loader\IniFileLoader +json: Symfony\Component\Translation\Loader\JsonFileLoader +mo: Symfony\Component\Translation\Loader\MoFileLoader +php: Symfony\Component\Translation\Loader\PhpFileLoader +po: Symfony\Component\Translation\Loader\PoFileLoader +ts: Symfony\Component\Translation\Loader\QtFileLoader +xlf: Symfony\Component\Translation\Loader\XliffFileLoader +yml: Symfony\Component\Translation\Loader\YamlFileLoader +``` + +### Database loaders + +Package includes database loaders for **[Doctrine 2](https://www.doctrine-project.org/)** and **[Nette Database 3](https://doc.nette.org/cs/3.0/database)**. + +#### Doctrine + +You must create a file with specific format in scanned dirs such as **messages.en_US.doctrine**. All parameters are optional, but the file has to exist. + +```neon +table: "My\Entity" # if you specify the entity key, "messages" from file name will be ignored +id: "id" # id column name, default is "id" +locale: "locale" # locale column name, default is "locale" +message: "message" # message column name, default is "message" +``` + +Add loader to translation configuration: + +```neon +translation: + loaders: + doctrine: Contributte\Translation\Loaders\Doctrine +``` + +Entity example: + +```php +addText('mail', 'form.mail.label') + ->setOption('description', new Contributte\Translation\Wrappers\Message('form.mail.description', [...]); +``` + +Or pass the not translatable texts: + +```php +$form->addSelect('country', 'form.country.label') + ->setItems([ + new Contributte\Translation\Wrappers\NotTranslate('Czech republic'), + new Contributte\Translation\Wrappers\NotTranslate('Slovak republic'), + ]); +``` + +### TranslationProviderInterface + +It is possible to pass additional translation resources from your compiler extensions by implementing the `TranslationProviderInterface`. + +```php +use Nette\DI\CompilerExtension; +use Contributte\Translation\DI\TranslationProviderInterface; + +class MyExtension extends CompilerExtension implements TranslationProviderInterface +{ + + public function getTranslationResources(): array + { + return [ + __DIR__ . '/../lang/', + ]; + } + +} +``` ## Development See [how to contribute](https://contributte.org/contributing.html) to this package. -This package is currently maintaining by these authors. +This package is currently maintained by these authors. - + ----- From f3510919b47d08667d089908b5f4ab494feb4b11 Mon Sep 17 00:00:00 2001 From: Oh My Felix Date: Sun, 16 Aug 2026 08:26:16 +0000 Subject: [PATCH 2/2] Docs: complete library quick start Co-authored-by: Milan Sulc --- .docs/README.md | 27 ++++ README.md | 371 ++---------------------------------------------- 2 files changed, 37 insertions(+), 361 deletions(-) create mode 100644 .docs/README.md diff --git a/.docs/README.md b/.docs/README.md new file mode 100644 index 00000000..424663d0 --- /dev/null +++ b/.docs/README.md @@ -0,0 +1,27 @@ +# Translation reference + +The root README contains the first-success setup. This reference covers the advanced integration surface. + +## Locale resolvers + +Configure resolver order with `translation.localeResolvers`. Available resolvers are `Router`, `Header`, `Parameter`, and `Session` from `Contributte\Translation\LocalesResolvers`; the default key is `locale`. + +## Message files and parameters + +Message files use `domain.locale.format`, for example `messages.en_US.neon`. Parameters are passed without percent signs: + +```neon +user.name.taken: "Sorry, the username %name% is already taken." +``` + +```latte +{_user.name.taken, [name => 'Ales']} +``` + +## Loaders + +NEON is configured by default. File loaders can be registered through `translation.loaders`; supported Symfony formats include array, CSV, INI, JSON, MO, PHP, PO, TS, XLIFF, and YAML. Doctrine and Nette Database loaders use marker files such as `messages.en_US.doctrine` and `messages.en_US.nettedatabase`. + +## Integration helpers + +Use `Wrappers\Message` for translatable form options and `Wrappers\NotTranslate` for literal values. Compiler extensions can provide additional scanned directories by implementing `TranslationProviderInterface`. diff --git a/README.md b/README.md index cd21e8fc..e80fc5e8 100644 --- a/README.md +++ b/README.md @@ -3,400 +3,49 @@

-

-

- - - - - -

- -

-Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte -

- -Symfony Translation integration for Nette Framework with locale resolving, Latte helpers, file loaders, and optional database loaders. - -## Versions - -| State | Version | Branch | PHP | Symfony | -|--------|----------|------------------|--------------|--------------| -| stable | `^2.0.0` | `master` | `^8.0` | `^6.0\|^7.0` | -| stable | `^1.0.0` | `php74_symfony5` | `^7.4\|^8.0` | `^5.0` | - -## Content -- [Installation](#installation) -- [Configuration](#configuration) - - [Locale resolvers](#locale-resolvers) -- [Examples](#examples) - - [Presenter](#presenter) - - [Model](#model) - - [Latte](#latte) - - [Neon](#neon) - - [Parameters in messages](#parameters-in-messages) -- [Loaders](#loaders) - - [File loaders](#file-loaders) - - [Database loaders](#database-loaders) - - [Doctrine](#doctrine) - - [Nette Database](#nette-database) -- [Features](#features) - - [Wrappers](#wrappers) - - [TranslationProviderInterface](#translationproviderinterface) -- [Development](#development) +Symfony Translation integration for Nette Framework. -## Installation +## Quick start -To install latest version of `contributte/translation` use [Composer](https://getcomposer.org). +Install the package and register its extension: ```bash composer require contributte/translation ``` -Register extension: - ```neon extensions: translation: Contributte\Translation\DI\TranslationExtension -``` - -## Configuration - -Basic configuration: -```neon translation: locales: - whitelist: [en, cs, sk] default: en - fallback: [en] dirs: - %appDir%/lang - returnOriginalMessage: true # to not translate undefined messages, default is true ``` -Note: The `fallback` configuration values should always reflect the **locale code** used in the file you wish to _fallback_ to (e.g. `en_US` for `messages.en_US.neon`, or `en` for `messages.en.neon`). - -### Locale resolvers -This configuration instructs the extension how to resolve the locale and the order in which it will do so: +Create `%appDir%/lang/messages.en.neon` (the filename is `domain.locale.neon`): ```neon -translation: - localeResolvers: - - Contributte\Translation\LocalesResolvers\Router +homepage: + welcome: Welcome! ``` -Available resolvers: - -- Contributte\Translation\LocalesResolvers\Router -- Contributte\Translation\LocalesResolvers\Header (HTTP header) -- Contributte\Translation\LocalesResolvers\Parameter (Get parameter) -- Contributte\Translation\LocalesResolvers\Session - -By default the `Router`, `Parameter` and `Session` resolvers expect the name of the parameter/key to be `locale`. - -## Examples - -### Presenter +Inject `Nette\Localization\ITranslator` and translate the message, or render it directly in Latte: ```php -translatorSessionResolver->setLocale($locale); - $this->redirect('this'); - } - - - public function renderDefault(): void - { - $this->translator->translate('domain.message'); - $prefixedTranslator = $this->translator->createPrefixedTranslator('domain'); - $prefixedTranslator->translate('message'); - } - -} +$message = $translator->translate('homepage.welcome'); ``` -### Model - -```php -translator = $translator; - } - -} -``` - -### Latte - -How to use on frontend. - ```latte -{_domain.message} -{_domain.message, $count} -{_domain.message, [name => "Ales"]} - -{translator domain} - {_message} - {_message, $count} - {_message, [name => "Ales"]} -{/translator} - -{var $myMessage = 'domain.message'} -{$myMessage|translate} -``` - -### Neon - -File name format: - -``` - locale - | - /--\ -messages.en_US.neon -\______/ \__/ - | | - domain extension -``` - -File content format: - -```neon -prefix: - for: "message" # messages.prefix.for -``` - -### Parameters in messages - -Sometimes it is convenient to include a dynamic parameter in the translation - as seen in the Latte examples above. - -Neon: - -```neon -user.name.taken: "Sorry, the username %name% is already taken, please try a different one." -``` - -Latte: - -```latte -{_user.name.taken, [name => "Ales"]} -``` - -Presenter/Model: - -```php -$this->translator->translate('user.name.taken', [name => 'Ales']); -``` - -**Note**: When passing parameters to the translator, the parameter names must not be enclosed in `%` characters. This is done by `Contributte/Translation` automatically. - -## Loaders - -By default the extension will look for `.neon` files. - -### File loaders - -```neon -array: Symfony\Component\Translation\Loader\ArrayLoader -csv: Symfony\Component\Translation\Loader\CsvFileLoader -dat: Symfony\Component\Translation\Loader\IcuDatFileLoader -res: Symfony\Component\Translation\Loader\IcuResFileLoader -ini: Symfony\Component\Translation\Loader\IniFileLoader -json: Symfony\Component\Translation\Loader\JsonFileLoader -mo: Symfony\Component\Translation\Loader\MoFileLoader -php: Symfony\Component\Translation\Loader\PhpFileLoader -po: Symfony\Component\Translation\Loader\PoFileLoader -ts: Symfony\Component\Translation\Loader\QtFileLoader -xlf: Symfony\Component\Translation\Loader\XliffFileLoader -yml: Symfony\Component\Translation\Loader\YamlFileLoader -``` - -### Database loaders - -Package includes database loaders for **[Doctrine 2](https://www.doctrine-project.org/)** and **[Nette Database 3](https://doc.nette.org/cs/3.0/database)**. - -#### Doctrine - -You must create a file with specific format in scanned dirs such as **messages.en_US.doctrine**. All parameters are optional, but the file has to exist. - -```neon -table: "My\Entity" # if you specify the entity key, "messages" from file name will be ignored -id: "id" # id column name, default is "id" -locale: "locale" # locale column name, default is "locale" -message: "message" # message column name, default is "message" -``` - -Add loader to translation configuration: - -```neon -translation: - loaders: - doctrine: Contributte\Translation\Loaders\Doctrine +{_homepage.welcome} ``` -Entity example: - -```php -addText('mail', 'form.mail.label') - ->setOption('description', new Contributte\Translation\Wrappers\Message('form.mail.description', [...]); -``` - -Or pass the not translatable texts: - -```php -$form->addSelect('country', 'form.country.label') - ->setItems([ - new Contributte\Translation\Wrappers\NotTranslate('Czech republic'), - new Contributte\Translation\Wrappers\NotTranslate('Slovak republic'), - ]); -``` - -### TranslationProviderInterface - -It is possible to pass additional translation resources from your compiler extensions by implementing the `TranslationProviderInterface`. - -```php -use Nette\DI\CompilerExtension; -use Contributte\Translation\DI\TranslationProviderInterface; - -class MyExtension extends CompilerExtension implements TranslationProviderInterface -{ - - public function getTranslationResources(): array - { - return [ - __DIR__ . '/../lang/', - ]; - } - -} -``` +Both forms render `Welcome!`. See [the detailed documentation](.docs/README.md) for locale resolvers, loaders, and reference material. ## Development See [how to contribute](https://contributte.org/contributing.html) to this package. - -This package is currently maintained by these authors. - - - - - ------ - -Consider to [support](https://contributte.org/partners.html) **contributte** development team. -Also thank you for using this package.