I18N and Fluent

I18N & Fluent Creating Multilingual Sites With Silverstripe CMS

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

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

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

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

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}">

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

i18n & Silverstripe

I18n & Silverstripe • i18n class • Static translations (_t()
and <% t %>) • Dynamic translations (fluent module) • see also: docs.silverstripe.org/en/4/developer_guides/i18n/#i18n

Class SilverStripe\i18n\i18n • Stores different data: ◦ current locale ◦
Date and time formats • Contains _t() method for translating static properties

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

Translate Static Content

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

More Advanced: _t() With Parameters

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

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)

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

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

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

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

Help Translating Core Modules

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/

Transifex Suggestions

And JavaScript?

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

Translating $Content: Fluent

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

Conﬁguring 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)

Default Locales In YML • use default_records for first time
installation

Translating Pages

Translating Pages: Locales

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

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

Translating DataObjects

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

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

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

Locale Menu Template

FluentState Of The Art • Your friend when dealing with
localised content programatically • Contains: ◦ Locale ◦ Domain ◦ IsDomainMode ◦ IsFrontent • ->withState(): get content in a different Locale

Tips, Tricks, Miscellaneous

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

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

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

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

I18N and Fluent

I18N and Fluent

More Decks by wernerkrauss

Other Decks in Technology

Featured

Transcript