tonyair/silverstripe-translatable
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-translatable synced 2024-10-22 11:05:59 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #275 from creative-commoners/pulls/2.3/fix-broken-links

Browse Source 
DOCS Fix broken links and some of the sample code
This commit is contained in:
Dylan Wagstaff 2018-03-21 14:22:33 +13:00 committed by GitHub
commit 22025df173
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 165 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -1,7 +1,7 @@
# Translatable module for SilverStripe CMS #
[![Build Status](https://secure.travis-ci.org/silverstripe/silverstripe-translatable.png?branch=2.1)](http://travis-ci.org/silverstripe/silverstripe-translatable)
![helpfulrobot](https://helpfulrobot.io/silverstripe/translatable/badge)
[![Build Status](https://secure.travis-ci.org/silverstripe/silverstripe-translatable.png)](http://travis-ci.org/silverstripe/silverstripe-translatable)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/silverstripe/silverstripe-translatable/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/silverstripe/silverstripe-translatable/?branch=master)
## Introduction ##
@ -31,4 +31,4 @@ and any new translations will be merged back to the project source code.
Please use [https://www.transifex.com/projects/p/silverstripe-translatable/](https://www.transifex.com/projects/p/silverstripe-translatable/) to contribute translations,
rather than sending pull requests with YAML files.
See the ["i18n" topic](http://doc.silverstripe.org/framework/en/trunk/topics/i18n) on doc.silverstripe.org for more details.
See the ["i18n" topic](https://docs.silverstripe.org/en/developer_guides/i18n/) on docs.silverstripe.org for more details.

105
docs/en/index.md
View File

@ -74,11 +74,7 @@ doesn't make much sense, like numeric values). More complex data model with rela
The Translatable module uses the "Storage in language rows" approach.
Alternatives:
* Tractorcow's [Fluent Module](https://github.com/tractorcow/silverstripe-fluent)
* UncleCheese's [TranslatableDataObject](http://www.leftandmain.com/silverstripe-tips/2012/04/03/translatabledataobject-insanely-simple-translation/) (open source)
* Kreationsbyran's [Multilingual Module 2.0](http://www.kreationsbyran.se/blogg/multilingual-module-2-0-for-silverstripe-cms-3-0/) (commercial)
An alternative is Tractorcow's [Fluent Module](https://github.com/tractorcow/silverstripe-fluent).
## Usage
@ -88,19 +84,22 @@ Alternatives:
Enabling Translatable through *add_extension()* in your *mysite/_config.php*:
:::php
```php
SiteTree::add_extension('Translatable');
SiteConfig::add_extension('Translatable'); // 2.4 or newer only
```
#### Through $extensions
:::php
class Page extends SiteTree {
```php
class Page extends SiteTree
{
private static $extensions = array(
"Translatable"
);
}
```
Make sure to rebuild the database through /dev/build after enabling `[api:Translatable]`.
@ -110,55 +109,56 @@ for the first time, as this locale will be written on all new records.
#### Setting the default locale
<div class="notice" markdown='1'>
**Important:** If the "default language" of your site is not english (en_US), please ensure to set the appropriate default
**Important:** If the "default language" of your site is not English (en_US), please ensure to set the appropriate default
language for your content before building the database with Translatable enabled
</div>
Example:
:::php
```php
Translatable::set_default_locale(<locale>);
// Important: Call add_extension() after setting the default locale
SiteTree::add_extension('Translatable');
```
For the Translatable class, a "locale" consists of a language code plus a region code separated by an underscore,
for example "de_AT" for German language ("de") in the region Austria ("AT").
See http://www.w3.org/International/articles/language-tags/ for a detailed description.
To ensure that your template declares the correct content language, please see [i18n](i18n#declaring_the_content_language_in_html).
To ensure that your template declares the correct content language, please see the [templates section](#templates).
### Usage
Getting a translation for an existing instance:
:::php
```php
$translatedObj = Translatable::get_one_by_locale('MyObject', 'de_DE');
```
Getting a translation for an existing instance:
:::php
```php
$obj = DataObject::get_by_id('MyObject', 99); // original language
$translatedObj = $obj->getTranslation('de_DE');
```
Getting translations through Translatable::set_reading_locale().
This is *not* a recommended approach, but sometimes unavoidable (e.g. for `[api:Versioned]` methods).
:::php
```php
$origLocale = Translatable::get_reading_locale();
Translatable::set_reading_locale('de_DE');
$obj = Versioned::get_one_by_stage('MyObject', "ID = 99");
Translatable::set_reading_locale($origLocale);
```
Creating a translation:
:::php
```php
$obj = new MyObject();
$translatedObj = $obj->createTranslation('de_DE');
```
### Usage for SiteTree
@ -182,13 +182,14 @@ a `locale` GET parameter (see `Translatable::choose_site_locale()`).
Note: You can't get Children() for a parent page in a different language
through set_reading_locale(). Get the translated parent first.
:::php
```php
// wrong
Translatable::set_reading_lang('de_DE');
$englishParent->Children();
// right
$germanParent = $englishParent->getTranslation('de_DE');
$germanParent->Children();
```
By default, the URLs generated for a page can only contain western characters ("ASCII").
You can configure this to accept the whole range of UTF8 characters as well.
@ -206,12 +207,13 @@ on SiteTree, not to any fields added in overloaded getCMSFields() implementation
By default, custom fields in the CMS won't show an original readonly value on a translated record, although they will save correctly. You can
attach this behaviour to custom fields by calling a helper function from your getCMSFields() and getSettingsFields() functions.
:::php
class Page extends SiteTree {
```php
class Page extends SiteTree
{
private static $db = array(
private static $db = [
'AdditionalProperty' => 'Text',
);
];
function getCMSFields() {
$fields = parent::getCMSFields();
@ -226,7 +228,8 @@ attach this behaviour to custom fields by calling a helper function from your ge
return $fields;
}
function getSettingsFields() {
function getSettingsFields()
{
$fields = parent::getSettingsFields();
// Add fields as usual
@ -239,6 +242,7 @@ attach this behaviour to custom fields by calling a helper function from your ge
return $fields;
}
}
```
### Excluding fields from translation
@ -247,22 +251,22 @@ You can exclude fields from translation by adding them to the `$translate_exclud
*Note: Actually there are some fields that are excluded from translation by default. These are defined in `Translatable::$translate_excluded_fields`:*
:::php
```php
/**
* Exclude these fields from translation
*
* @var array
* @config
*/
private static $translate_excluded_fields = array(
private static $translate_excluded_fields = [
'ViewerGroups',
'EditorGroups',
'CanViewType',
'CanEditType',
'NewTransLang',
'createtranslation'
);
:::
];
```
Excluding fields from translation can be done via `mysite/config/_config.yml` or by setting the variable directly in your object.
@ -319,7 +323,7 @@ as defined by the "MasterTranslationID" property. This relation is optional, mea
create translations which have no representation in the "default language".
This "original" doesn't have to be in a default language, meaning
a french translation can have a german original, without either of them having a representation
in the default english language tree.
in the default English language tree.
Caution: There is no versioning for translation groups,
meaning associating an object with a group will affect both stage and live records.
@ -350,15 +354,16 @@ HTML-templates adjust to this.
### "Default" languages
<div class="warning" markdown='1'>
**Important:** If the "default language" of your site is not english (en_US),
**Important:** If the "default language" of your site is not English (en_US),
please ensure to set the appropriate default language for
your content before building the database with Translatable enabled
</div>
Example:
:::php
```php
Translatable::set_default_locale(<locale>);
```
@ -384,23 +389,23 @@ in the database.
### Switching languages
A widget now exists to switch between languages, and is [available here](http://www.silverstripe.org/Language-Chooser-Widget/).
You can easily make your own switchers with the following basic tools. To stay friendly to caches and search engines, each
translation of a page must have a unique URL.
By URL:
:::php
```php
http://<mysite>/mypage/?locale=de_DE
```
By user preference (place this in your Page_Controller->init() method):
:::php
```php
$member = Member::currentUser();
if($member && $member->Locale) {
Translatable::set_current_locale($member->Locale);
}
```
### Templates
@ -427,7 +432,7 @@ through the *getTranslations()* method. We can use this method in our template t
shows all available translations in an unordered list with links to the same page in a different language. The example
below can be inserted in any of your templates, for example `themes/blackcandy/templates/Layout/Page.ss`.
:::php
<% if Translations %>
<ul class="translations">
<% loop Translations %>
@ -453,8 +458,9 @@ of different pages differ.
For this case place the following function in your Page_Controller:
:::php
public function PageByLang($url, $lang) {
```php
public function PageByLang($url, $lang)
{
$SQL_url = Convert::raw2sql($url);
$SQL_lang = Convert::raw2sql($lang);
@ -465,8 +471,9 @@ For this case place the following function in your Page_Controller:
}
return $page;
}
```
So, for example if you have a german page "Kontakt", which should be translated to english as "Contact", you may use:
So, for example if you have a german page "Kontakt", which should be translated to English as "Contact", you may use:
<% loop PageByLang(Kontakt,de_DE) %>
@ -481,8 +488,8 @@ Example:
### Enabling the _t() function in templates
If you're looking to use [the _t() function](http://doc.silverstripe.com/doku.php?id=i18n#the_t_function) in template
files, you'll need to [set the i18n locale](/topics/translation#setting_the_i18n_locale) first.
If you're looking to use the [`_t() function`](https://docs.silverstripe.org/en/developer_guides/i18n/#the-t-function) in template
files, you'll need to [set the i18n locale](#setting-the-i18n-locale) first.
(The reasoning is as follows: Translatable doesn't set the i18n locale. Historically these were two separate systems,
but they're reasonably interchangeable for a front-end website. The distinction is mainly valid for the CMS, because you
@ -493,7 +500,7 @@ want the CMS to be in English (`i18n`), but edit pages in different languages (`
You can set the `i18n` locale value which is used to format dates, currencies and other regionally different values to
the same as your current page locale.
:::php
```php
class Page_Controller extends ContentController {
public function init() {
parent::init();
@ -503,6 +510,7 @@ the same as your current page locale.
}
}
}
```
### Adding a new locale
@ -510,20 +518,19 @@ the same as your current page locale.
The `i18n` logic has lookup tables for common locales in i18n::$common_locales, which is a subset of i18n::$all_locales.
If your locale is not present here, you can simply add it through `mysite/_config/config.yml`:
:::yml
```yml
i18n:
common_locales:
de_AT:
name: 'German (Austria)'
native: 'Deutsch (Österreich)'
```
This should e.g. enable you to use `$Locale.Nice` in template code.
## Related
* [translate.silverstripe.org](http://translate.silverstripe.org): Starting point for community-driven translation of the Silverstripe UI
* [i18n](i18n): Developer-level documentation of Silverstripe's i18n capabilities
* `[api:Translatable]`: DataObject-interface powering the website-content translations
* ["Translatable ModelAdmin" module](http://silverstripe.org/translatablemodeladmin-module/): An extension which allows
translations of `[api:DataObject]`s inside `[api:ModelAdmin]`
* [Translations](http://translate.silverstripe.org): Developer documentation on how to use translations with a template
* ["Translatable ModelAdmin" module](https://github.com/silverstripe-archive/silverstripe-translatablemodeladmin): An extension which allows
translations of `[api:DataObject]`s inside `[api:ModelAdmin]` (no longer supported)