Download the PHP package bummzack/translatable-dataobject without Composer

translatable-dataobject

An extension for SilverStripe 3.1 that adds translations of fields to DataObjects. Instead of creating new rows for translations, translations are added as columns. This way, there's only one DataObject instance which is consistent across all localizations, but which has localized fields.

This module requires the translatable module to be installed. Credit goes to Uncle Cheese which inspired my with his TranslatableDataObject

Requirements

• SilverStripe 3.1 or newer
• translatable module

Installation

Use composer:

composer require bummzack/translatable-dataobject

Alternatively clone/download this repository into a folder in your SilverStripe installation folder.

Usage

Defining content locales

The ideal/recommended way to define the locales for the modules is to set the allowed locales for the Translatable module. That way, the available locales are consistent throughout the CMS. Example:

If you would like to set the locales for the translatable-dataobject module manually/separately, you can specify them via YAML config:

If both of these calls are being omitted, the module will get the locales from the site content using:

Using this setup requires you to run dev/build whenever you add a new translation language to the system though.

Enabling translations

To make a DataObject translatable, add the TranslatableDataObjectextension via YAML config file, like so:

Run dev/build afterwards, so that the additional DB fields can be created. By default, all Varchar, Text and HTMLText fields will be translated, while all other fields remain untouched. To alter these default-fields, you can configure them like this:

If you would like to specify the fields to localize manually, you can add them via translatable_fields YAML config:

Alternatively, you can also set the fields to translate in a static field on your DataObject. So inside your MyDataObject class you could add something like this:

Translations in the CMS

Imagine you have a TestimonialPage that has_many testimonials and you're managing these Testimonials in a GridField.

The DataObject (Testimonial)

Let's start with the Testimonial DataObject:

Most of this should look familiar. We add the TranslatableDataObject extension and declare which fields should be translated by setting translatable_fields. The very same could also be done via YAML config (see config examples above).

The page (TestimonialPage)

Now for the Testimonial-Page:

This looks even more like a regular page and you probably wonder what's so special here. The only thing that changed is that we use $this->Master()->Testimonials() instead of $this->Testimonials() as the GridField datasource. With this setup, you should be able to switch between different languages in the CMS and edit the testimonials each in the current language. Give it a try

Forms and ModelAdmin

The TranslatableDataObject extension comes with several helper methods that will make it easier for you to build translatable forms for the CMS. The default behavior (if you don't implement getCMSFields yourself, also known as scaffolding) is that you'll only see the form fields for the currently active locale, which is ideal if you're working in the Pages section of the CMS where you're always working in one language tree. For locales other than the default locale, you'll see the original content as a read-only field below each form-field (same behavior as the translatable module provides for pages).

Of course you can also implement the getCMSFields method yourself. Here's an example:

When we're not in the default locale, we transform the fields using a TranslatableFormFieldTransformation instance. This is very similar to what you're probably used to from the translatable module with its Translatable_Transformation. What this does is: It takes the given form-field and replaces it's name and content with the translated content. The original content will appear as read-only below the form field.

If you wish to get an input field for the current locale, there's a helper method for that called getLocalizedFormField. It will automatically create an appropriate input field for the given field name. So if your field is of type Varchar, you'll get a TextField instance. A HTMLText will return a HtmlEditorField instance etc.

Example:

Using the TranslatableFormFieldTransformation class or the getLocalizedFormField method should provide enough tools to build custom backend forms for most of your needs.

There's another helper method which is especially useful in a ModelAdmin context (because in ModelAdmin you're not working in one locale as it's the case with the Pages section). The helper method is called getTranslatableTabSet and will give you a TabSet with an individual Tab for every language. Here's how you use it:

Doing this will give you a tab for each language, each tab containing the translatable form fields. If you have fields that aren't being translated, yet still need to be edited via backend, do something along these lines:

Files and Images

Usually you'll also want to translate some fields of the file class. Enabling translation is simple by adding the following configuration:

The TranslatedFile extension will generate a tab per language within the Files Section of the CMS. In addition it adds a helper method (getUploadEditorFields) to use when within a locale-context. You can use this to provide translated fields for editing files in a UploadField. Here's an example:

Usage and templates

Whenever you'll have to access your DataObjects, remember to use $this->Master()->Relation() instead of $this->Relation().

Master() is a handy method in translatable-dataobject/code/extensions/TranslatableUtility.php. This extension will automatically be added to each SiteTree object with the installation of the translatable-dataobject module. It's a helper-method to get the master-translation of a page and can also be very useful in templates. So if you would like to output all testimonials in a template, you'd use:

Another helpful method to be used in templates is Languages. It will return an ArrayList with all information you need to build a language-navigation. Drop something like this in your template:

Or you can just include a prepackaged template:

This will create a list of all available content-languages. The link will point to the translated page or to the home-page of that language if there's no translation in that language.

Todo:

• CMS UI improvements
• Better integration with existing components such as the GridField
• Better access for relations (eg. get the translated page when getting a has_one relation)

Limitations

The module currently only supports translations of DB fields that are part of the DataObject itself. Fields that are being added by extensions aren't translatable.

Since this extension adds more fields to a table, it is important to note that the number of localized fields and the number of languages could cause problems with the underlying database. Imagine a DataObject with 10 localizable fields and a site that will be translated into 5 other languages. This would add 50 columns to the table.

According to the MySQL documentation, the hard-limit of columns for a MySQL table is at 4096, which should be sufficient for most setups. Other RDBMS might have other limitations though.