I18N and Fluent

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

Transcript

1. I18N & Fluent
   Creating Multilingual Sites With Silverstripe CMS
   

   View Slide

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
   

   View Slide

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
   

   View Slide

4. i18n
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

9. i18n
   &
   Silverstripe
   

   View Slide

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
    

    View Slide

11. Class SilverStripe\i18n\i18n
    ● Stores different data:
    ○ current locale
    ○ Date and time formats
    ● Contains _t() method for translating static properties
    

    View Slide

12. Interface SilverStripe\i18n\i18nEntityProvider
    ● Interface to return a list of
    provided translations for
    this object
    ● used by DataObject
    ● can be overwritten in
    subclasses
    

    View Slide

13. Translate Static Content
    

    View Slide

14. _t() _t(Class.KEY, Fallback Translation)
    

    View Slide

15. More Advanced: _t() With Parameters
    

    View Slide

16. _t() In Templates: <%t … %>
    

    View Slide

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)
    

    View Slide

18. Default Translations For DataObjects
    ● Provided by
    DataObject::provideI18nEntities()
    ● Singular & Pluralname
    ● Fieldlabels and Relations shortcodes:
    db_xx, has_one_xxx etc…
    ● Pluralisation
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

22. Help Translating
    Core Modules
    

    View Slide

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/
    

    View Slide

24. View Slide

25. Transifex Suggestions
    

    View Slide

26. And JavaScript?
    

    View Slide

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
    

    View Slide

28. Translating $Content:
    Fluent
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

31. View Slide

32. Default Locales In YML
    ● use default_records for first time installation
    

    View Slide

33. Translating Pages
    

    View Slide

34. Translating Pages: Locales
    

    View Slide

35. Translating Pages: Copy Locales
    In the Localisation tab: Actions near “Save” and “Publish”:
    

    View Slide

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
    

    View Slide

37. Translating DataObjects
    

    View Slide

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()
    

    View Slide

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
    

    View Slide

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
    

    View Slide

41. Locale Menu Template
    

    View Slide

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
    

    View Slide

43. Tips, Tricks, Miscellaneous
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

47. Thank You
    www.silverstrip.es
    www.netwerkstatt.at
    

    View Slide