diff --git a/.docs/README.md b/.docs/README.md index 64b708dc..424663d0 100644 --- a/.docs/README.md +++ b/.docs/README.md @@ -1,358 +1,27 @@ -# Translation +# Translation reference -## 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) +The root README contains the first-success setup. This reference covers the advanced integration surface. -## Setup +## Locale resolvers -Require package: +Configure resolver order with `translation.localeResolvers`. Available resolvers are `Router`, `Header`, `Parameter`, and `Session` from `Contributte\Translation\LocalesResolvers`; the default key is `locale`. -```bash -composer require contributte/translation -``` - -Register extension: - -```neon -extensions: - translation: Contributte\Translation\DI\TranslationExtension -``` - -## Configuration +## Message files and parameters -Basic configuration: +Message files use `domain.locale.format`, for example `messages.en_US.neon`. Parameters are passed without percent signs: ```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'); - } - -} +user.name.taken: "Sorry, the username %name% is already taken." ``` -### 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} +{_user.name.taken, [name => 'Ales']} ``` -### 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/', - ]; - } - -} -``` +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 8d6fb31d..e80fc5e8 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,51 @@ ![](https://heatbadger.now.sh/github/readme/contributte/translation/)

- - - - -

-

- - - - - + + +

-

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

+Symfony Translation integration for Nette Framework. -## Usage +## Quick start -To install the latest version of `contributte/translation` use [Composer](https://getcomposer.org). +Install the package and register its extension: ```bash composer require contributte/translation ``` -## Documentation -For details on how to use this package, check out our [documentation](.docs). +```neon +extensions: + translation: Contributte\Translation\DI\TranslationExtension -## 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` | +translation: + locales: + default: en + dirs: + - %appDir%/lang +``` -## Development +Create `%appDir%/lang/messages.en.neon` (the filename is `domain.locale.neon`): -See [how to contribute](https://contributte.org/contributing.html) to this package. +```neon +homepage: + welcome: Welcome! +``` + +Inject `Nette\Localization\ITranslator` and translate the message, or render it directly in Latte: -This package is currently maintaining by these authors. +```php +$message = $translator->translate('homepage.welcome'); +``` - - - +```latte +{_homepage.welcome} +``` ------ +Both forms render `Welcome!`. See [the detailed documentation](.docs/README.md) for locale resolvers, loaders, and reference material. -Consider to [support](https://contributte.org/partners.html) **contributte** development team. -Also thank you for using this package. +## Development + +See [how to contribute](https://contributte.org/contributing.html) to this package.