wickedone/phrase-translation-provider

symfony phrase translation provider bridge

1.2.0 2024-11-22 06:16 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0
• psr/cache: ^3.0
• psr/event-dispatcher: ^1.0
• symfony/event-dispatcher-contracts: ^3.5.0
• symfony/http-client: ^5.4 || ^6.4
• symfony/mime: ^5.4 || ^6.4
• symfony/translation: ^5.4 || ^6.4

Requires (Dev)

• infection/infection: ^0.29
• phpstan/phpstan: ^2.0.2
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0.1
• phpunit/phpunit: ^11.4.3
• roave/security-advisories: dev-latest

MIT

• wicliff wolda

README

symfony phrase translation provider bridge

⚠️ this translation provider has been integrated into symfony starting at version 6.4. this repository will be archived once lts expires for symfony 5.4

installation

composer require wickedone/phrase-translation-provider

dsn example

PHRASE_DSN=phrase://PROJECT_ID:API_TOKEN@default?userAgent=myProject

dsn elements

• PROJECT_ID: can be retrieved in phrase from project settings > API > Project ID
• API_TOKEN: can be created in your phrase profile settings
• default: endpoint, defaults to api.phrase.com

required dsn query parameters

• userAgent: please read this for some examples.

see fine tuning your phrase api calls for additional dsn options

service phrase provider

in your services.yaml add the following to enable the phrase provider.

Symfony\Component\Translation\Bridge\Phrase\PhraseProviderFactory:
    tags: ['translation.provider_factory']
    arguments:
        $defaultLocale: '%kernel.default_locale%'
        $loader: '@translation.loader.xliff'
        $xliffFileDumper: '@translation.dumper.xliff'
        $cache: '@cache.app'

and in your translations.yaml you can add:

framework:
    translator:
        providers:
            phrase:
                dsn: '%env(PHRASE_DSN)%'
                domains: ~
                locales: ~

phrase locale names

translations being imported using the symfony xlf format in phrase, locales are matched on locale name in phrase. therefor it's necessary the locale names should be as defined in RFC4646 (e.g. pt-BR rather than pt_BR). not doing so will result in phrase creating a new locale for the imported keys.

locale creation

if you define a locale in your translation.yaml which is not configured in your phrase project, it will be automatically created. deletion of locales however, is (currently) not managed by this provider.

domains as tags

translations will be tagged in phrase with the symfony translation domain they belong to. check the wickedone/phrase-tag-bundle if you need help managing your tags in phrase

cache

the read responses from phrase are cached to speed up the read and delete method of this provider. therefor the factory should be initialised with a PSR-6 compatible cache adapter.

events

to enable you to perform post-processing on translation values and / or keys, two events are dispatched by this provider class.

PhraseReadEvent

after reading the catalogue from phrase, the resulting TranslatorBag is dispatched in a PhraseReadEvent prior to being returned from the read method.

PhraseWriteEvent

before writing the catalogue to phrase, the TranslatorBag is dispatched in a PhraseWriteEvent.

fine tuning your phrase api calls

you can fine tune the read and write methods of this provider by adding query parameters to your dsn configuration. general usage is read|write[option_name]=value

example: phrase://PROJECT_ID:API_TOKEN@default?read[encoding]=UTF-8&write[update_descriptions]=0

see tables below for available options and, if applicable, their default values.

read

in order to read translations from phrase the download locale call is made to the phrase api. this call provides the following options.

write

in order to write translations to phrase the upload call is made to the phrase api. this call provides the following options.