mirror of
https://github.com/silverstripe/silverstripe-translatable
synced 2024-10-22 11:05:59 +02:00
Caveats section for README
This commit is contained in:
parent
745b2bcc8e
commit
1d7a84b637
@ -4,13 +4,12 @@
|
|||||||
|
|
||||||
This page introduces developers to using the CMS for creating content in multiple languages.
|
This page introduces developers to using the CMS for creating content in multiple languages.
|
||||||
|
|
||||||
Please refer to the `i18n` class in `sapphire` for a internationalization, globalization and localization support of built-in datatypes as well as translating templates and PHP code.
|
Please refer to the [`i18n` class](http://doc.silverstripe.org/framework/en/topics/i18n)
|
||||||
|
in SilverStripe framework for a internationalization, globalization and
|
||||||
|
localization support of built-in datatypes as well as translating templates and PHP code.
|
||||||
|
|
||||||
Translations can be enabled for all subclasses of `[api:DataObject]`, so it can easily be implemented into existing code
|
Translations can be enabled for all subclasses of [`DataObject`](http://doc.silverstripe.org/framework/en/topics/datamodel),
|
||||||
with minimal interference.
|
so it can easily be implemented into existing code with minimal interference.
|
||||||
|
|
||||||
Warning: If you're upgrading from a SilverStripe version prior to 2.3.2, please migrate your datamodel before using the
|
|
||||||
extension (see below).
|
|
||||||
|
|
||||||
## Screenshots
|
## Screenshots
|
||||||
|
|
||||||
@ -32,6 +31,35 @@ extension (see below).
|
|||||||
*CMS: Create a new translation*
|
*CMS: Create a new translation*
|
||||||
|
|
||||||
|
|
||||||
|
## Caveats
|
||||||
|
|
||||||
|
There are several ways to model multilingual content in a relational database.
|
||||||
|
It is important to understand these differences in order to make an informed
|
||||||
|
decision about which one fits your content model best.
|
||||||
|
|
||||||
|
* **Storage in language columns**: Each translated value is stored in a new database column
|
||||||
|
alongside its original record, e.g. a `Content` column gets extended to `Content_de` and `Content_fr`.
|
||||||
|
|
||||||
|
* Advantages: Translation can be limited to certain columns.
|
||||||
|
* Disadvantages: If applied to complex data like hierarchical pages, it only works if the content structure
|
||||||
|
is very similar between languages. It would be difficult to e.g. have a new page section just in one language,
|
||||||
|
and still retain all the framework's features (e.g. permission checks).
|
||||||
|
* **Storage in language rows**: Each translated record gets copied to a new row in the same table,
|
||||||
|
retaining the original database column layout.
|
||||||
|
|
||||||
|
* Advantages: Allows for flexible structures like page trees per language,
|
||||||
|
and permission checks per language. Works transparently with most other modules which modify queries
|
||||||
|
(e.g. the "subsites" module).
|
||||||
|
* Disadvantages: All-or-nothing approach to column translation (including columns where translation
|
||||||
|
doesn't make much sense, like numeric values). More complex data model with relational tables.
|
||||||
|
|
||||||
|
The Translatable module uses the "Storage in language rows" approach.
|
||||||
|
|
||||||
|
Alternatives:
|
||||||
|
|
||||||
|
* 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)
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
### Configuration
|
### Configuration
|
||||||
@ -187,7 +215,7 @@ attach this behaviour to custom fields by using Translatable_Transformation as s
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Translating theHomepage
|
### Translating the Homepage
|
||||||
|
|
||||||
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
|
||||||
@ -362,12 +390,6 @@ Example:
|
|||||||
<% end_control %>
|
<% end_control %>
|
||||||
|
|
||||||
|
|
||||||
### Language Chooser Widget
|
|
||||||
|
|
||||||
You can use a widget on your website to provide a list of links for switching languages:
|
|
||||||
[download](http://silverstripe.org/Language-Chooser-Widget-2/)
|
|
||||||
|
|
||||||
|
|
||||||
### Enabling the _t() function in templates
|
### 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
|
If you're looking to use [the _t() function](http://doc.silverstripe.com/doku.php?id=i18n#the_t_function) in template
|
||||||
@ -375,29 +397,11 @@ files, you'll need to [set the i18n locale](/topics/translation#setting_the_i18n
|
|||||||
|
|
||||||
(The reasoning is as follows: Translatable doesn't set the i18n locale. Historically these were two separate systems,
|
(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
|
but they're reasonably interchangeable for a front-end website. The distinction is mainly valid for the CMS, because you
|
||||||
want the CMS to be in English (`[api:i18n]`), but edit pages in different languages (`[api:Translatable]`).)
|
want the CMS to be in English (`i18n`), but edit pages in different languages (`Translatable`).)
|
||||||
|
|
||||||
### Migrating from 2.1 datamodel
|
|
||||||
|
|
||||||
The datamodel of `[api:Translatable]` changed significantly between its original release in SilverStripe 2.1 and SilverStripe
|
|
||||||
2.3.2. See our [discussion on the
|
|
||||||
mailinglist](http://groups.google.com/group/silverstripe-dev/browse_thread/thread/91e26e1f78d3c1b4/bd276dd5bbc56283?lnk=gst&q=translatable#bd276dd5bbc56283).
|
|
||||||
|
|
||||||
To migrate a database that was built with SilverStripe 2.1.x or 2.2.x, follow these steps:
|
|
||||||
|
|
||||||
* Upgrade your SilverStripe installation to at least 2.3.2 (see [upgrading](/installation/upgrading))
|
|
||||||
* Backup your database content
|
|
||||||
* Login as an administrator
|
|
||||||
* Run `http://mysite.com/dev/build`
|
|
||||||
* Run `http://mysite.com/dev/tasks/MigrateTranslatableTask`
|
|
||||||
|
|
||||||
Please see the `[api:MigrateTranslatableTask]` for
|
|
||||||
limitations of this migration task - not all your data will be preserved.
|
|
||||||
|
|
||||||
|
|
||||||
### Setting the i18n locale
|
### Setting the i18n locale
|
||||||
|
|
||||||
You can set the `[api:i18n]` locale value which is used to format dates, currencies and other regionally different values to
|
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.
|
the same as your current page locale.
|
||||||
|
|
||||||
:::php
|
:::php
|
||||||
@ -414,7 +418,7 @@ the same as your current page locale.
|
|||||||
|
|
||||||
### Adding a new locale
|
### Adding a new locale
|
||||||
|
|
||||||
The `[api: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.php`:
|
If your locale is not present here, you can simply add it through `mysite/_config.php`:
|
||||||
|
|
||||||
:::php
|
:::php
|
||||||
|
Loading…
Reference in New Issue
Block a user