Internationalize your Symfony application, the right way

Translating an application is a big step while you develop an international project. Translation process of an application can be very tough. It can remain laborious even after the first release.
So, we have a new type of workmate: dear developers, product owners, designers, let me introduce translators with whom we will have to work efficiently!
Together, we will have to make sure that the translations stay up to date on production. How? This is exactly what we will be talking about in this conference. Tools like php-translation bundle, Loco or Transifex will be very useful to your team. We will plug them in Symfony to create an efficient workflow. We will also define responsibilities for developers, translators and designers. Everything to ease the translation process from development environment to production without any pain! At the end of this talk, you will be looking forward to implementing these amazing solutions!

Transcript

1. Internationalize your Symfony application, the right way
2. I am Mathieu Santostefano Web Developer at One of maintainers of php-translation organization @welcomattic on Twitter & GitHub Hello!
3. Sorry for my french accent
4. Why translation? In 2016, a client in passenger transport domain needed a new European website I have worked on this translation process
5. Promise of this talk Define a process and a workflow to ease the translation of your application, with dedicated tools for each person involved in the project.
6. i18n Internationalization: Designing a software that can be adapted to various languages without engineering changes. Some vocabulary l10n Localization: Process of adapting an internationalized software for a specific region or language by translating texts, adapting date, currency formats. g11n Globalization: Combination of i18n and l10n process.
7. Internationalize a Symfony Application Why? When? How?
8. Why? ◉ All your visitors don’t speak your language ◉ Even if you target one country, all people in a country don’t speak the same language (Switzerland, Belgium, …) ◉ Centralize UI texts in files instead of spreading them in many templates.
9. When? ◉ At the very beginning of the project ◉ Even for one language. Because centralizing UI texts in files will make your life easier later ◉ I18n an existing application is very expensive in time and money. And boring.
10. How? ◉ Define a clear process with responsibilities for every involved workmate ◉ Use dedicated tools for developers, translators and QA ◉ Document the workflow and train your team to the tools.
11. How does software i18n work?
12. Translation file format standards .po, .mo, .ini, .yaml, .lang, .json, …
13. .po, .mo, .ini, .yaml, .lang, .json, … ◉ There are many language file formats ◉ But, there is one standard ◉ Defined by the OASIS* consortium ◉ It is XLIFF *OASIS: Organization for the Advancement of Structured Information Standards
14. XLIFF ◉ XML Localisation Interchange File Format ◉ 1.2 last revised 1st February 2008 ◉ 2.0 last revised 5th August 2014 https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=xliff
15. XLIFF ◉ It is a standard, Symfony supports 1.2 and 2.0 ◉ Has the best support in professional Translation Management Systems ◉ Symfony supports <notes> tag, useful to give more context to translation keys
16. “ Use the XLIFF Format for Your Translation Files https://symfony.com/doc/current/best_practices.html#internationalization
17. Pick a tool Desktop POEdit SaaS
18. Distribution of roles Who’s doing what?
19. Assigning tasks Developers • Define nomenclature for translation keys • Create translation keys • Use XLIFF notes tags to add context Translators • Translate obviously • Read notes tags provided by developers to understand context of keys Product Owners / QA • Ensure that translations are ok in a staging environment • Could mark translation as incorrect
20. <?xml version="1.0" encoding="utf-8"?> <xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0" srcLang="fr-FR" trgLang="fr-FR"> <file id="messages.fr_FR"> <unit id="IrB7E1R" name="user_account.last_login"> <notes> <note>parameters:-/note> <note>'formatted_datetime': '12 novembre 2020 à 19h22'-/note> -/notes> <segment> <source>user_account.last_login-/source> <target>Dernière connexion le {formatted_datetime}-/target> -/segment> -/unit> -/file> -/xliff>
21. Common mistakes What should we avoid?
22. A cumbersome process ◉ Translators don’t have to edit XLIFF files. ◉ Code and text must not be mixed up ◉ Developers don’t have to export new translations files manually
23. Translation keys management user_profile.edit_form_part_1.fields.name.label ❌ form.label.name ✅ For ambiguous keys, use the <notes> tag of XLIFF. https://php-translation.readthedocs.io/en/latest/best-practice/index.html#translation-keys
24. With code In the translations directory of your application. Versioned with Git. SaaS In a Translation Management System SaaS, like Loco or Crowdin. my_app_en_GB_v14_202 0_03_11_0318pm.xlsx XLSX file, attached to an email conversation between developers and translators. Store translations
25. “ Hi developer, there’s a typo on the homepage first title, could you please fix it and deploy it ASAP? A product owner
26. What do we have now? File format XLIFF, full featured standard, supported by Symfony SaaS tool with an API It allows developers to send new keys, and translators to translate them Keys nomenclature Developers have guidelines to create translations keys Roles Everyone knows what they have to do
27. I made a poll few weeks ago 56 responses
28. What do we miss? Something to automate translations synchronization between SaaS API and all instances of your application.
29. Let’s build the workflow! Photo by Xavi Cabrera on Unsplash
30. Developers create keys Workflow Translators do their job Developers send keys to the SaaS API Automatic fetching of translations Translations are up to date without manual deployment
31. <Code time!/>
32. Will we need a bundle? YES But, which one?
33. symfony/translation JMSTranslationBundle LexikTranslationBundle php-translation/ symfony-bundle Maintained ✅ ✅ ✅ ✅ Loaders (read translation files) ✅ ✅ (homemade) ❌ ✅ Dumpers (write translation files) ✅ ✅ (homemade) ✅ (only in database) ✅ GUI ❌ ✅ ✅ ✅ Domains management ✅ ✅ ✅ ✅ (depends on SaaS) SaaS API Clients ❌ ❌ ❌ ✅ Storages Files Files Database Multiple (files, SaaS, database, …) Compare bundles
34. “ php-translation/symfony-bundle WINS!
35. translation_adapter_loco: projects: my_application_messages: api_key: '%env(LOCO_MESSAGES_API_KEY)%' domains: ['messages'] my_application_security: api_key: '%env(LOCO_SECURITY_API_KEY)%' domains: [‘security’]
36. translation: locales: ["en", "fr", "sv"] configs: app: dirs: ["%kernel.root_dir%/Resources/views", "%kernel.root_dir%/-./src"] output_dir: "%kernel.root_dir%/Resources/translations" excluded_names: ["*TestCase.php", "*Test.php"] remote_storage: ["php_translation.adapter.loco"] output_format: "xlf"
37. -/15 * * * * bin/console translation:download --env=prod
38. php-translation/symfony-bundle This bundle allow you to: • Add new keys from the Symfony Profiler Translation panel • Upload and download translations from SaaS to your application
39. Workflow Developers create keys Translators do their job Developers send keys to the SaaS API Automatic fetching of translations Translations are up to date without manual deployment
40. “ Oh, there’s a typo on the homepage first title. Hurry up, let’s fix it in {chosen SaaS}, and wait for the next translations fetch in X minutes A product owner
41. Some ProTips© Write permissions Ensure that your user has write permissions on translations directory. Be careful with crontab Don’t fetch your translation too often, it will clear translation cache each time. Phone number l10n Use odolbeau/phone-number-bundle And format international phone numbers painlessly. Translations in test env? Decorate the Symfony Translator, return the $id except if $domain == ‘route’. In your tests files, check if the keys are in your page.
42. One more thing...
43. What if this workflow didn’t require third party bundle?
44. PR #38475 is open!
45. PR #38475 is open! It brings Translation Providers to Symfony. It lets you use the Translation SaaS you want, use or write the Provider, and automate your translation workflow!
46. PR #38475 is open! You will be able to: ◉ Push new translations keys, remove obsolete ones to your chosen translation SaaS ◉ Pull new or updated translations ◉ Do both for each locale and/or domain
47. Thanks a lot to ◉ Olivier Dolbeau to initiate this PR with me ◉ Tobias Nyholm and all contributors of php-translation ◉ JoliCode for sponsoring time to let me work on this PR ◉ Symfony team for selecting this talk
48. Any questions ? You can find me at @welcomattic on Twitter and GitHub Thanks!