Revision: 2130
Author: andreassolberg
Date: Fri Jan 22 07:16:41 2010
Log: add documentation on the new translation format
http://code.google.com/p/simplesamlphp/source/detail?r=2130
Added:
/trunk/docs/simplesamlphp-translation.txt
=======================================
--- /dev/null
+++ /trunk/docs/simplesamlphp-translation.txt Fri Jan 22 07:16:41 2010
@@ -0,0 +1,195 @@
+SimpleSAMLphp Translation Portal
+================================================================
+
+<!--
+ This file is written in Markdown syntax.
+ For more information about how to use the Markdown syntax, read here:
+ http://daringfireball.net/projects/markdown/syntax
+-->
+
+ * Version: `$Id$`
+
+SimpleSAMLphp supports multiple languages.
+
+ * The SimpleSAMLphp Translation Portal
+ * Language definition file
+ * Translation file
+
+
+## How translated terms are referred from a template
+
+Here is an example of how two terms are included in a template from
dictionary files:
+
+ <h2><?php echo $this->t('{core:frontpage:about_header}'); ?></h2>
+ <p><?php echo $this->t('{core:frontpage:about_text}'); ?></p>
+
+In this example, two translated terms are included: `about_header` and
`about_text`. Both these terms are found in a dictionary file named
`frontpage`, inside the module named `core`.
+
+**Note:** An important use-case here is that you can create your own
module, that includes a new theme that overrides some of the default
templates. You may in this template refer to both terms from the existing
dictionary files, but you can also add new dictionary files in your new
module that may introduce new alternative terms.
+
+## The definition file
+
+When the template library is about to lookup the translation of a term, it
will lookup
+
+ * the definition file, for the English translation, and
+ * the translation file, for translation to other languages.
+
+When developing new functionalities it is common to start by just
introducing the definition file, then upload the definition file to the
SimpleSAMLphp translation portal, perform translation, and then download
the translation files back in to the module.
+
+SimpleSAMLphp will always fallback to the English translation using the
definition file, both:
+
+ * when the term is not translated into the *current selected language*,
and
+ * when the translation file is not available at all.
+
+The name of the definition file is `BASENAME.definition.json`, where the
term is referred to like this: `{MODULENAME:BASENAME:TERM}`. The file MUST
be placed in the followng location:
`modules/MODULENAME/dictionaries/BASENAME.definition.json`.
+
+The content of the defintion file is a *JSON encoded array* of `term =>
definition`, where definition is an array with an required `en` index for
the english translation, and the value is the English text.
+
+Here is an example of a definition file with three terms:
+
+ {
+ "header": {
+ "en": "Missing cookie"
+ },
+ "description": {
+ "en": "You appear to have disabled cookies in your browser. Please
check the settings in your browser, and try again."
+ },
+ "retry": {
+ "en": "Retry"
+ }
+ }
+
+Note: you may not include other languages in the definition files, the
`en` index is used in order to at a later point in time introduce more meta
information for each term, like in example:
+
+ "header": {
+ "en": "Missing cookie",
+ "_note": "This text shows up on the error page when the browser do not
support cookies."
+ },
+
+To summarize the pattern of the defintion file is as follows:
+
+ {
+ "TERM1": {
+ "en": "English text 1"
+ },
+ "TERM2": {
+ "en": "English text 2"
+ }
+ }
+
+## The translation file
+
+The translation file is similar to the definition file, but including
translation to languages others than English.
+
+This file is reccomended to never write manually, but instead use the
SimpleSAMLphp translation portal, and then download generated translation
files.
+
+The structure of the file is identical to the definition files, except
from the language index, which now is not `en`, but the actual langauge
that is translated:
+
+
+ {
+ "TERM1": {
+ "no": "Norsk tekst 1",
+ "da": "Dansk tekst 1"
+ },
+ "TERM2": {
+ "no": "Norsk tekst 2",
+ "da": "Dansk tekst 2"
+ }
+ }
+
+## The SimpleSAMLphp Translation Portal
+
+The SimpleSAMLphp translation portal is available here:
+
+ * <https://translation.rnd.feide.no/>
+
+Use Feide OpenIdP to login, select the application you want to translate,
simpleSAMLphp or your own application, then start translate to your
langauge.
+
+## The `translation.php` command line script
+
+The `translation.php` script is available in the `bin` directory of
SimpleSAMLphp.
+
+The script requires that the config file `translation.php` is copied from
`config-templates` to the `config` directory.
+
+The script may be used to these tasks:
+
+ * upload definition files
+ * download defintion files
+ * download translation files
+
+### Uploading defintion files
+
+You probably do not have access to upload definition files for the
simpleSAMLphp application. But, from January 2010, the translation portal
is generic to host multiple independent applications. What you may do is to
contact Andreas to add your own application to the translation portal,
where you off course have access to upload definition files.
+
+**Note**: an application may very well be a local simpleSAMLphp module
that you run.
+
+To add a new application to the SimpleSAMLphp translation portal, contact
Andreas with the following information:
+
+ * name of the application
+ * Feide OpenID userids of the individuals that should have access to
upload definition files
+ * a list of languages that should be expored
+
+If you want to upload a definition file, edit the `translation.php` config
file to include the ID of your application.
+
+Then manually create a definition file as described in the section *The
definition file* above.
+
+Next run the script as follows:
+
+ bin/translation.php push
modules/MODULENAME/dictionaries/BASENAME.definition.json
+
+Output example:
+
+ Action: [push]
+ Application: [simplesamlphp]
+ File orig: [modules/core/dictionaries/no_cookie.definition.json]
+ File base: [no_cookie]
+ Using OAuth to authenticate you to the translation portal
+ Successfully read OAuth Access Token from cache
[_6d20d3830e7823304881ca9b829bedb0caf8877c8c]
+ New definition file [no_cookie] stored in application [simplesamlphp] for
user [[email protected]] ...
+
+The script uses OAuth to connect your session on the command line client
with the translation portal, then you need to login using Feide OpenIdP.
+
+
+
+### Deleting defintion files
+
+Is perfomed via the webbased translation portal.
+
+### Downloading defintion files
+
+Seldom used, as the defintion file is manually created locally. Anyway:
+
+ bin/translation.php pulldef
modules/MODULENAME/dictionaries/BASENAME.definition.json
+
+Ooutput example:
+
+ Action: [pulldef]
+ Application: [simplesamlphp]
+ File orig: [modules/core/dictionaries/no_cookie.definition.json]
+ File base: [no_cookie]
+
+
+### Downloading translation files
+
+ bin/translation.php pull
modules/MODULENAME/dictionaries/BASENAME.translation.json
+
+Note: it is optional whether you use `BASENAME.defintion.json` or
`BASENAME.translation.json`
+
+Example output:
+
+ Action: [pull]
+ Application: [simplesamlphp]
+ File orig: [modules/core/dictionaries/no_cookie.definition.json]
+ File base: [no_cookie]
+
+Often you would like to pull translation from a number of definition files
distributed in many different modules. Then you may use some helpful
commands like:
+
+ find . -name '*.definition.json' | xargs -n 1 bin/translation.php pull
+
+Note: Be careful when you checkin
+
+### Converting old translation file to new definition file
+
+ bin/translation.php convert modules/MODULENAME/dictionaries/BASENAME.php
+
+And a new definition file is created using the new JSON format.
--
You received this message because you are subscribed to the Google Groups
"simpleSAMLphp commits" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/simplesamlphp-commits?hl=en.
