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

I18N and Fluent

wernerkrauss
September 30, 2021

I18N and Fluent

wernerkrauss

September 30, 2021
Tweet

More Decks by wernerkrauss

Other Decks in Technology

Transcript

  1. I18N & Fluent
    Creating Multilingual Sites With Silverstripe CMS

    View full-size 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 full-size 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 full-size slide

  4. 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 full-size slide

  5. 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 full-size slide

  6. 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 full-size slide

  7. 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 full-size slide

  8. i18n
    &
    Silverstripe

    View full-size slide

  9. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  12. Translate Static Content

    View full-size slide

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

    View full-size slide

  14. More Advanced: _t() With Parameters

    View full-size slide

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

    View full-size slide

  16. 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 full-size slide

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

    View full-size slide

  18. 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 full-size slide

  19. 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 full-size slide

  20. 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 full-size slide

  21. Help Translating
    Core Modules

    View full-size slide

  22. 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 full-size slide

  23. Transifex Suggestions

    View full-size slide

  24. And JavaScript?

    View full-size slide

  25. 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 full-size slide

  26. Translating $Content:
    Fluent

    View full-size slide

  27. 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 full-size slide

  28. 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 full-size slide

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

    View full-size slide

  30. Translating Pages

    View full-size slide

  31. Translating Pages: Locales

    View full-size slide

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

    View full-size slide

  33. 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 full-size slide

  34. Translating DataObjects

    View full-size slide

  35. 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 full-size slide

  36. 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 full-size slide

  37. 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 full-size slide

  38. Locale Menu Template

    View full-size slide

  39. 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 full-size slide

  40. Tips, Tricks, Miscellaneous

    View full-size slide

  41. 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 full-size slide

  42. 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 full-size slide

  43. 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 full-size slide

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

    View full-size slide