Author: Derick Rethans Date: 2006-01-25 14:09:16 +0100 (Wed, 25 Jan 2006) New Revision: 2025
Log: - Translation tutorial continuation. Added: packages/Translation/trunk/docs/translations/ packages/Translation/trunk/docs/translations/translation-nb_NO.xml packages/Translation/trunk/docs/translations/translation-nl_NL.xml packages/Translation/trunk/docs/tutorial_example_02.php Modified: packages/Translation/trunk/docs/tutorial.txt packages/Translation/trunk/docs/tutorial_example_01.php Added: packages/Translation/trunk/docs/translations/translation-nb_NO.xml =================================================================== --- packages/Translation/trunk/docs/translations/translation-nb_NO.xml 2006-01-25 09:18:54 UTC (rev 2024) +++ packages/Translation/trunk/docs/translations/translation-nb_NO.xml 2006-01-25 13:09:16 UTC (rev 2025) @@ -0,0 +1,27 @@ +<!DOCTYPE TS><TS> +<context> + <name>tutorial/headers</name> + <message> + <source>header1</source> + <translation>overskrift 1</translation> + </message> +</context> +<context> + <name>tutorial/descriptions</name> + <message> + <source>desc1</source> + <translation>desc1 (norsk)</translation> + </message> + <message> + <source>desc2</source> + <translation>desc2 (norsk)</translation> + </message> +</context> +<context> + <name>search</name> + <message> + <source>The %fruit is round.</source> + <translation>%Fruit er rund.</translation> + </message> +</context> +</TS> Added: packages/Translation/trunk/docs/translations/translation-nl_NL.xml =================================================================== --- packages/Translation/trunk/docs/translations/translation-nl_NL.xml 2006-01-25 09:18:54 UTC (rev 2024) +++ packages/Translation/trunk/docs/translations/translation-nl_NL.xml 2006-01-25 13:09:16 UTC (rev 2025) @@ -0,0 +1,16 @@ +<!DOCTYPE TS><TS> +<context> + <name>tutorial/headers</name> + <message> + <source>header1</source> + <translation type="unfinished"></translation> + </message> +</context> +<context> + <name>search</name> + <message> + <source>Search for '%search_string' returned %matches matches.</source> + <translation>Er zijn %matches items gevonden bij het zoeken naar '%search_string'.</translation> + </message> +</context> +</TS> Modified: packages/Translation/trunk/docs/tutorial.txt =================================================================== --- packages/Translation/trunk/docs/tutorial.txt 2006-01-25 09:18:54 UTC (rev 2024) +++ packages/Translation/trunk/docs/tutorial.txt 2006-01-25 13:09:16 UTC (rev 2025) @@ -56,7 +56,7 @@ serving as an example they have very little function. -.. _`Qt's Linguist files`: http://www.trolltech.com/products/qt/internationalization.html +.. _Qt's Linguist files: http://www.trolltech.com/products/qt/internationalization.html Installation ============ @@ -70,7 +70,82 @@ Basic Usage =========== +In the most simple case all that your application wants to do is access +translated versions of the strings that it uses. In most cases the strings used +in an application will be English, but of course that is not necessary. In the +first version of the component we only support `Qt's Linguist files`_ (TS +files) which groups translatable strings together in contexts. The TS file +format is handled by the ezcTranslationTsBackend class. This backend requires +one setting (the location where to find the translation) and has one option +(the format for the filename for each locale). +In the first example we assume that all translations are stored in the +"translations/" directory, and that the filename consists of "translation-" +followed by the locale name and ".xml". The locale name itself is a freeform +field, but we recommend to use the `ISO639-1`_ language code, followed by a _, +followed by the ISO3166_ country code. e.g. nb_NO for Bokmål/Norway or nl_BE +for Dutch/Belgium. + +.. include:: tutorial_example_01.php + :literal: + +In the above example we create a backend object in lines 4 and 5. We tell the +backend where to find the translations, and what the format of the translation +filename is. The string "[LOCALE]" will automatically be replaced with the +locale name when opening the translation file. With the configured backend we +then construct a manager in line 7. In line 8 and 9 we ask the manager to +return the contexts "tutorial/headers" and "tutorial/desciptions" for the +"nb_NO" locale. When you ask the manager to retrieve the content it first +checks its internal cache if the context is there already. If the context is +available in the cache it will simply return it. If the context is not in the +cache, it will defer the retrieving to the backend, store the results in its +cache and return the context. + +In many cases there are parameters to your translated strings, for example to +fill in a name of an article. In this case a solution would be to separate the +translatable string into two parts, and just concat them together with the +parameter on the correct place. However, it is also possible that the order of +parameters changes when you translate a string. For example the +English string "Search for 'appelmoes' returned 3 matches" can be translated in Dutch +to: "Er zijn 3 items gevonden bij het zoeken naar 'appelmoes'". The simple +concattenation mechanism then no longer works. Luckily the Translation +component supports parameterized strings in two different ways: with +numerical replacement identifiers (%1, %2, etc.) and with associative +identifiers (%search_string, %matches). In the following example we show how to +use this: + +.. include:: tutorial_example_02.php + :literal: + +The first lines are the same as in the first example. But this time we retrieve +the same context for two different locales (in line 8 and 9). In line 11 and 12 +we request the translation for "Search for '%search_string' returned %matches +matches.". This sentence has two parameters (search_string and matches) for +which the values are provided in array that is passed as second parameter to +the getTranslation() method. + +The translation for the English "The apple is round" is in Norwegian "Applet er +rund". With the name of the fruit being the parameter you can see that in +Norwegian the parameter value needs to have its first letter uppercased, as +it's the start of a sentence. The translation system supports this by +specifying the first letter of the parameter name in the translated string as a +capital letter. For a TS format file this looks like: :: + + <source>The %fruit is round.</source> + <translation>%Fruit er rund.</translation> + +When the first letter of a parameter name in the translated string is a +capital, the translation system will also uppercase the first letter of the +parameter value. The output of the whole script is therefore: :: + + Er zijn 4 items gevonden bij het zoeken naar 'appelmoes'. + Epplet er rund. + + +.. _`ISO639-1`: http://www.loc.gov/standards/iso639-2/langcodes.html +.. _ISO3166: http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html + + Iteration ========= @@ -79,6 +154,10 @@ ======= +More Information +================ + + .. Local Variables: Modified: packages/Translation/trunk/docs/tutorial_example_01.php =================================================================== --- packages/Translation/trunk/docs/tutorial_example_01.php 2006-01-25 09:18:54 UTC (rev 2024) +++ packages/Translation/trunk/docs/tutorial_example_01.php 2006-01-25 13:09:16 UTC (rev 2025) @@ -1,3 +1,15 @@ <?php require_once 'tutorial_autoload.php'; + +$backend = new ezcTranslationTsBackend( dirname( __FILE__ ). '/translations' ); +$backend->setOptions( array( 'format' => 'translation-[LOCALE].xml' ) ); + +$manager = new ezcTranslationManager( $backend ); +$headersContext = $manager->getContext( 'nb_NO', 'tutorial/headers' ); +$descriptionContext = $manager->getContext( 'nb_NO', 'tutorial/descriptions' ); + +echo $headersContext->getTranslation( 'header1' ), "\n"; +echo $descriptionContext->getTranslation( 'desc1' ), "\n"; +echo $descriptionContext->getTranslation( 'desc2' ), "\n"; + ?> Added: packages/Translation/trunk/docs/tutorial_example_02.php =================================================================== --- packages/Translation/trunk/docs/tutorial_example_02.php 2006-01-25 09:18:54 UTC (rev 2024) +++ packages/Translation/trunk/docs/tutorial_example_02.php 2006-01-25 13:09:16 UTC (rev 2025) @@ -0,0 +1,16 @@ +<?php +require_once 'tutorial_autoload.php'; + +$backend = new ezcTranslationTsBackend( dirname( __FILE__ ). '/translations' ); +$backend->setOptions( array( 'format' => 'translation-[LOCALE].xml' ) ); + +$manager = new ezcTranslationManager( $backend ); +$dutch = $manager->getContext( 'nl_NL', 'search' ); +$norsk = $manager->getContext( 'nb_NO', 'search' ); + +$params = array( 'search_string' => 'appelmoes', 'matches' => 4 ); +echo $dutch->getTranslation( "Search for '%search_string' returned %matches matches.", $params ), "\n"; + +$params = array( 'fruit' => 'epplet' ); +echo $norsk->getTranslation( "The %fruit is round.", $params ), "\n"; +?> Property changes on: packages/Translation/trunk/docs/tutorial_example_02.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
