I18N and Fluent

Talk given at https://2021.stripecon.eu

1. I18N & Fluent Creating Multilingual Sites With Silverstripe CMS
2. Who am I? • Werner M. Krauß • Living in Bad Ischl, Austria • wmk on slack • PHP since 1998 • Freelancer since 2006 (netwerkstatt) • Silverstripe since 2009 (V 2.3) • Creator of www.silverstrip.es • Co-founder of S2Hub
3. What’s This Talk About? • Definition of Internationalisation • How to make a multilingual site in Silverstripe ◦ What can be translated ◦ Helpful tools • Tips and tricks
4. i18n
5. What is i18n and l10n? • I18n is the abbreviation for “internationalisation” • I18n = process of designing software that it can be adapted to various languages and regions without code changes • L10n is the abbreviation for “localisation” • L10n uses i18n to add new locales
6. Language vs Locale • A language can be spoken in many countries or regions • Depending on the region, we have different locales • de_DE vs de_AT vs de_CH (Januar vs Jänner) • en_100 for English international • See wikipedia: Internationalization_and_localization
7. What’s Affected By i18n • Texts (buttons, labels, content). Content, charsets (utf-8 ftw), ltr, rtl • Pluralisation rules • Date and time formats, calendar systems; time zones • Number formats • Currency formats • Punctuation, quotes etc… (“…” vs «…» in Fench) • SEO <html lang="{$ContentLocale}">
8. How To Make Software Multi-Language 1. Internationalisation ◦ make it possible to translate content 2. Localisation ◦ translate the content to different locales 3. Quality Assurance ◦ Culturally appropriate syntax and translations ◦ English e.g. for international audience, not only native speakers
9. i18n & Silverstripe
10. I18n & Silverstripe • i18n class • Static translations (_t() and <% t %>) • Dynamic translations (fluent module) • see also: docs.silverstripe.org/en/4/developer_guides/i18n/#i18n
11. Class SilverStripe\i18n\i18n • Stores different data: ◦ current locale ◦ Date and time formats • Contains _t() method for translating static properties
12. Interface SilverStripe\i18n\i18nEntityProvider • Interface to return a list of provided translations for this object • used by DataObject • can be overwritten in subclasses
13. Translate Static Content
14. _t() _t(Class.KEY, Fallback Translation)
15. More Advanced: _t() With Parameters
16. _t() In Templates: <%t … %>
17. Translated Strings: lang/de.yml • Language.yml is the base file for a language (e.g. de.yml) • Single translations can be overruled by locale.yml (e.g. de_AT.yml)
18. Default Translations For DataObjects • Provided by DataObject::provideI18nEntities() • Singular & Pluralname • Fieldlabels and Relations shortcodes: db_xx, has_one_xxx etc… • Pluralisation
19. Translating FieldLabels Only In yml • in DataObject::fieldLabels() • db_xxx • has_one_xxx • has_many_xxx • many_many_xxx • belongs_many_many_xxx • belongs_to_xxx is missing
20. I18nTextCollectorTask • Collects translated text strings in code and templates and writes them to yml files • Only in modules, currently not in themes :( • Needs PHPUnit installed to work • run e.g. http://localhost/dev/tasks/i18nTextCollectorTask/?module=mymodule
21. Fix Missing Strings From Modules In Your Project 1. find the missing string 2. add or modify lang yml in /app/lang/ 3. flush, so Silverstripe knows the new translation string Works also when you want to change a default translation
22. Help Translating Core Modules
23. Translate Core Modules • www.transifex.com • Great tool, for keeping translations in sync over multiple languages • CLI tools for uploading source language strings and downloading translations • When using it, only modify source locale in your repo directly, never the translations • see docs.silverstripe.org/en/4/contributing/translation_process/
25. Transifex Suggestions
26. And JavaScript?
27. Translate JS strings • Similar to _t() in php • include library and JS language files • see also docs.silverstripe.org/en/4 /developer_guides/i18n/ #javascript-usage
28. Translating $Content: Fluent
29. Installing Fluent • run composer require tractorcow/silverstripe-fluent ^5 • Run a dev/build to ensure all additional table fields have been generated • Configure your locales in the /admin/locales section • Pages are automatically translated • Publish pages in each of the locales you want them to be visible in
30. Configuring Locales • Configure locales in the backend • Different domains or URL segments per locale possible • Fallback locales possible (e.g. if you have different locales per language)
32. Default Locales In YML • use default_records for first time installation
33. Translating Pages
34. Translating Pages: Locales
35. Translating Pages: Copy Locales In the Localisation tab: Actions near “Save” and “Publish”:
36. Translating DataObjects • add TractorCow\Fluent\Extension\FluentExtension • for versioned objects use TractorCow\Fluent\Extension\FluentVersionedExtension • translates all text fields automatically • ...or configure it manually using the $translate config
37. Translating DataObjects
38. Translate Custom Form Fields • Use $this->beforeUpdateCMSFields to add fields that should be translated • Fields are translated in updateCMSFields that might be called in parent::getCMSFields()
39. Translating Relations • TractorCow\Fluent\Extension\FluentFilteredExtension • filters relations in the frontend • disabled in the backend • choose on which locales a DataObject is shown • See silverstripe-fluent/docs/en/configuration.md #locale-based-filter-configuration
40. Locale Menu aka Language Switcher • Fluent has a built in helper to create a locale switcher • loop over locales and display a link to the locale
41. Locale Menu Template
42. FluentState Of The Art • Your friend when dealing with localised content programatically • Contains: ◦ Locale ◦ Domain ◦ IsDomainMode ◦ IsFrontent • ->withState(): get content in a different Locale
43. Tips, Tricks, Miscellaneous
44. Locales vs Countries • A country can have multiple locales, e.g. ◦ Switzerland (DE, FR, IT) ◦ Finland (FI, SV) ◦ Canada (EN, FR) ◦ New Zealand (EN, MI) ◦ ... • A language can be spoken in multiple countries
45. Gotchas… • Partial caching should know the locale ◦ otherwise only one locale is cached ◦ content doesn’t match the end user’s locale Been there, done that
46. Useful Extensions And Ideas • derralf/silverstripe-fluent-tweaks ◦ set order/sorting ◦ hide from LocaleMenu ◦ hide from MetaTags • lekoala/silverstripe-multilingual ◦ improved text collector task • level51/silverstripe-fluent-autotranslate ◦ Automatic translation of content via Google Translate API • Idea: Export all content of a specific source language for passing to a translator
47. Thank You www.silverstrip.es www.netwerkstatt.at