Upgrade to Pro — share decks privately, control downloads, hide ads and more …

I18N and Fluent

September 30, 2021

I18N and Fluent


September 30, 2021

More Decks by wernerkrauss

Other Decks in Technology


  1. 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
  2. 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
  3. 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
  4. 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
  5. 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}">
  6. 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
  7. I18n & Silverstripe • i18n class • Static translations (_t()

    and <% t %>) • Dynamic translations (fluent module) • see also: docs.silverstripe.org/en/4/developer_guides/i18n/#i18n
  8. Class SilverStripe\i18n\i18n • Stores different data: ◦ current locale ◦

    Date and time formats • Contains _t() method for translating static properties
  9. Interface SilverStripe\i18n\i18nEntityProvider • Interface to return a list of provided

    translations for this object • used by DataObject • can be overwritten in subclasses
  10. 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)
  11. Default Translations For DataObjects • Provided by DataObject::provideI18nEntities() • Singular

    & Pluralname • Fieldlabels and Relations shortcodes: db_xx, has_one_xxx etc… • Pluralisation
  12. 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
  13. 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
  14. 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
  15. 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/
  16. 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
  17. 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
  18. 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)
  19. 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
  20. 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()
  21. 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
  22. 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
  23. FluentState Of The Art • Your friend when dealing with

    localised content programatically • Contains: ◦ Locale ◦ Domain ◦ IsDomainMode ◦ IsFrontent • ->withState(): get content in a different Locale
  24. 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
  25. 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
  26. 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