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 #282 from matthewntt/patch-1

Browse Source 
Update index.md
This commit is contained in:
Robbie Averill 2019-03-14 12:00:28 +13:00 committed by GitHub
commit fed2f1a869
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
docs/en/index.md
View File

@ -80,9 +80,9 @@ An alternative is Tractorcow's [Fluent Module](https://github.com/tractorcow/sil
### Configuration ### Configuration
#### ThroughObject::add_extension() #### Through Object::add_extension()
Enabling Translatable through *add_extension()* in your *mysite/_config.php*: Enabling Translatable through `add_extension()` in your `mysite/_config.php`:
```php ```php
SiteTree::add_extension('Translatable'); SiteTree::add_extension('Translatable');
@ -102,14 +102,14 @@ class Page extends SiteTree
``` ```
Make sure to rebuild the database through /dev/build after enabling `[api:Translatable]`. Make sure to rebuild the database through `/dev/build` after enabling `[api:Translatable]`.
Use the correct set_default_locale() before building the database Use the correct `set_default_locale()` before building the database
for the first time, as this locale will be written on all new records. for the first time, as this locale will be written on all new records.
#### Setting the default locale #### Setting the default locale
<div class="notice" markdown='1'> <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 language for your content before building the database with Translatable enabled
</div> </div>
@ -143,7 +143,7 @@ $obj = DataObject::get_by_id('MyObject', 99); // original language
$translatedObj = $obj->getTranslation('de_DE'); $translatedObj = $obj->getTranslation('de_DE');
``` ```
Getting translations through Translatable::set_reading_locale(). Getting translations through `Translatable::set_reading_locale()`.
This is *not* a recommended approach, but sometimes unavoidable (e.g. for `[api:Versioned]` methods). This is *not* a recommended approach, but sometimes unavoidable (e.g. for `[api:Versioned]` methods).
```php ```php
@ -179,8 +179,8 @@ In either case, you'll need to take care that the appropriate "reading language"
before showing links to other pages on a website, for example through before showing links to other pages on a website, for example through
a `locale` GET parameter (see `Translatable::choose_site_locale()`). a `locale` GET parameter (see `Translatable::choose_site_locale()`).
Note: You can't get Children() for a parent page in a different language Note: You can't get `Children()` for a parent page in a different language
through set_reading_locale(). Get the translated parent first. through `set_reading_locale()`. Get the translated parent first.
```php ```php
// wrong // wrong
@ -202,10 +202,10 @@ Keep in mind that the `[api:Translatable]` extension currently doesn't support t
translated - all custom properties will automatically be fetched from their translated record on the database. This means translated - all custom properties will automatically be fetched from their translated record on the database. This means
you don't have to explicitly mark any custom properties as being translatable. you don't have to explicitly mark any custom properties as being translatable.
The `[api:Translatable]` decorator applies only to the getCMSFields() method on DataObject or SiteTree and the getSettingsFields() The `[api:Translatable]` decorator applies only to the `getCMSFields()` method on `DataObject` or `SiteTree` and the `getSettingsFields()`
on SiteTree, not to any fields added in overloaded getCMSFields() implementations. See Translatable->updateCMSFields() for details. on `SiteTree`, not to any fields added in overloaded `getCMSFields()` implementations. See `Translatable->updateCMSFields()` for details.
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 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. attach this behaviour to custom fields by calling a helper function from your `getCMSFields()` and `getSettingsFields()` functions.
```php ```php
class Page extends SiteTree class Page extends SiteTree
@ -311,7 +311,7 @@ or directly in our `Page` class:
Every homepage has a distinct URL, the default language is /home, a German translation by default would be /home-de_DE. Every homepage has a distinct URL, the default language is /home, a German translation by default would be /home-de_DE.
They can be accessed like any other translated page. If you want to access different homepages from the "root" without a They can be accessed like any other translated page. If you want to access different homepages from the "root" without a
URL, add a "locale" GET parameter. The German homepage would also be accessible through /?locale=de_DE. URL, add a `locale` GET parameter. The German homepage would also be accessible through `/?locale=de_DE`.
For this to work, please ensure that the translated homepage is a direct translation of the default homepage, and not a For this to work, please ensure that the translated homepage is a direct translation of the default homepage, and not a
new page created through "Create page...". new page created through "Create page...".
@ -319,7 +319,7 @@ new page created through "Create page...".
### Translation groups ### Translation groups
Each translation can have an associated "master" object in another language which it is based on, Each translation can have an associated "master" object in another language which it is based on,
as defined by the "MasterTranslationID" property. This relation is optional, meaning you can as defined by the `MasterTranslationID` property. This relation is optional, meaning you can
create translations which have no representation in the "default language". create translations which have no representation in the "default language".
This "original" doesn't have to be in a default language, meaning 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 a french translation can have a german original, without either of them having a representation
@ -327,7 +327,7 @@ in the default English language tree.
Caution: There is no versioning for translation groups, Caution: There is no versioning for translation groups,
meaning associating an object with a group will affect both stage and live records. meaning associating an object with a group will affect both stage and live records.
SiteTree database table (abbreviated) `SiteTree` database table (abbreviated)
ID | URLSegment | Title | Locale ID | URLSegment | Title | Locale
---- | ------------ | ----------- | ----------- ---- | ------------ | ----------- | -----------
@ -335,7 +335,7 @@ ID | URLSegment | Title | Locale
`2` | `ueber-uns` | `Über uns` | `de_DE` `2` | `ueber-uns` | `Über uns` | `de_DE`
`3` | `contact` | `Contact` | `en_US` `3` | `contact` | `Contact` | `en_US`
SiteTree_translationgroups database table `SiteTree_translationgroups` database table
TranslationGroupID | OriginalID TranslationGroupID | OriginalID
------------------ | ---------- ------------------ | ----------
@ -343,7 +343,7 @@ TranslationGroupID | OriginalID
`99` | `2` `99` | `2`
`199` | `3` `199` | `3`
### CharacterSets ### Character sets
<div class="warning" markdown='1'> <div class="warning" markdown='1'>
**Caution:** Does not apply any character-set conversion, it is assumed that all content **Caution:** Does not apply any character-set conversion, it is assumed that all content
@ -381,7 +381,7 @@ of the currently displayed page, and falls back to `i18n::get_locale()`).
Disabling Translatable after creating translations will lead to all Disabling Translatable after creating translations will lead to all
pages being shown in the default sitetree regardless of their language. pages being shown in the default sitetree regardless of their language.
It is advised to start with a new database after uninstalling Translatable, It is advised to start with a new database after uninstalling Translatable,
or manually filter out translated objects through their "Locale" property or manually filter out translated objects through their `Locale` property
in the database. in the database.
## Recipes ## Recipes
@ -398,7 +398,7 @@ By URL:
http://<mysite>/mypage/?locale=de_DE http://<mysite>/mypage/?locale=de_DE
``` ```
By user preference (place this in your Page_Controller->init() method): By user preference (place this in your `Page_Controller->init()` method):
```php ```php
$member = Member::currentUser(); $member = Member::currentUser();
@ -417,7 +417,7 @@ Declaring the language for HTML templates:
:::ss :::ss
<html lang="$ContentLocale">...</html> <html lang="$ContentLocale">...</html>
Declaring the language for HTML templates: Declaring the language for XHTML templates:
:::ss :::ss
<html lang="$ContentLocale" xml:lang="$ContentLocale" xmlns= "http://www.w3.org/1999/xhtml"> <html lang="$ContentLocale" xml:lang="$ContentLocale" xmlns= "http://www.w3.org/1999/xhtml">
@ -428,11 +428,11 @@ has only one language. But how does a user coming to your English default langua
of this page? of this page?
By default, SilverStripe core doesn't provide any switching of languages through sessions or browser cookies. As a By default, SilverStripe core doesn't provide any switching of languages through sessions or browser cookies. As a
SEO-friendly CMS, it contains all this information in the URL. Each page in SilverStripe is aware of its translations SEO-friendly CMS, it contains all this information in the URL. Each page in SilverStripe is aware of its translations
through the *getTranslations()* method. We can use this method in our template to build a simple language switcher. It through the `getTranslations()` method. We can use this method in our template to build a simple language switcher. It
shows all available translations in an unordered list with links to the same page in a different language. The example 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`. below can be inserted in any of your templates, for example `themes/blackcandy/templates/Layout/Page.ss`.
```php
<% if Translations %> <% if Translations %>
<ul class="translations"> <ul class="translations">
<% loop Translations %> <% loop Translations %>
@ -445,10 +445,10 @@ title="$Title">
<% end_loop %> <% end_loop %>
</ul> </ul>
<% end_if %> <% end_if %>
```
Keep in mind that this will only show you available translations for the current page. The `$Locale.Nice` casting will
Keep in mind that this will only show you available translations for the current page. The $Locale.Nice casting will just work if your locale value is registered in `i18n::get_common_locales()`.
just work if your locale value is registered in i18n::get_common_locales().
### Page-control ### Page-control
@ -456,7 +456,7 @@ If you want to put static links in your template, which link to a site by their
Page(page-url) %>`. For sites which use Translatable, this is not possible for more than one language, because the url's Page(page-url) %>`. For sites which use Translatable, this is not possible for more than one language, because the url's
of different pages differ. of different pages differ.
For this case place the following function in your Page_Controller: For this case place the following function in your `Page_Controller`:
```php ```php
public function PageByLang($url, $lang) public function PageByLang($url, $lang)
@ -515,7 +515,7 @@ class Page_Controller extends ContentController {
### Adding a new locale ### Adding a new locale
The `i18n` logic has lookup tables for common locales in i18n::$common_locales, which is a subset of i18n::$all_locales. 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`: If your locale is not present here, you can simply add it through `mysite/_config/config.yml`:
```yml ```yml