Update:Remora Localization - Revision history

Wenzel: moved updating locale files chapter under static l10n

2007-01-27T18:59:28Z

moved updating locale files chapter under static l10n

@@ Line 67: / Line 67: @@
 The full gettext manual is [http://www.gnu.org/software/gettext/manual/ available] and intimidating, but it will probably answer any other questions.
-==Dynamic Strings==
+=== Updating gettext files in the remora tree ===
 We need strings from the database to be localizable as well.  This includes all english content in the remora code (Categories, etc.) but also the addons themselves (title, description, etc.)
@@ Line 175: / Line 198: @@
     newDB.executeSql("delete from addons where id = ''targetAddonIDForDeletion''")
     newDB.executeManySql("delete from translations where id = %s", listOfTranslationsToDelete)

Clouserw: /* Dynamic Strings */

2007-01-10T17:48:34Z

Dynamic Strings

@@ Line 71: / Line 71: @@
 We need strings from the database to be localizable as well.  This includes all english content in the remora code (Categories, etc.) but also the addons themselves (title, description, etc.)
-The ''translations'' table is the hub of our localization.  It was born out of the Pear::Translation2 specs, but we decided that the pear class wouldn't fit our needs.  The ''translations'' table has 3 primary columns, and then all the additional comments are supported languages.  The 3 main columns are:
+Our original method was related closely to Pear::Translation2, but Lars showed us the error of our ways with the great Lars Digression of 2006.  He came up with a new method that allowed referential integrity and a more stable table structure, which is detailed below:
-* `foreign_id` - The unique id of the row in the foreign table (that you are getting the translation for)
+make the translations table a simple three column table - a non-unique id, a locale and a string.  Together the non-unique id and the locale make up the primary key.  For each column in another table that needs a translation, replace that column with a partial key to the translations table id column.  Whenever you select a row needing translations from a table, you simply add a join to the translations table using the partial key and the locale.
   +------------------+------------------+------+-----+---------+-------+

Clouserw: /* Static Strings (PHP and gettext) */

2007-01-10T17:43:20Z

Static Strings (PHP and gettext)

← Older revision		Revision as of 17:43, 10 January 2007
Line 38:		Line 38:

	Note that we use ordinal parameters (%1$s) rather than simply %s which allows localizers to use a different order of the parameters (or drop some altogether).		Note that we use ordinal parameters (%1$s) rather than simply %s which allows localizers to use a different order of the parameters (or drop some altogether).

			=== Static pluralization ===

			Gettext also supports some pluralization (for example, adding an 's' to the end of words when there are more than 1). To support that, we need to add a Plurarl-Forms header to the .po file, like so:

			: <code>"Plural-Forms: nplurals=2; plural=n != 1;\n"</code>

			This Plural-Forms header is appropriate for english, other languages are given [http://www.gnu.org/software/gettext/manual/html_node/gettext_150.html here].

			After you have the plural forms header, you need to change the translation in the .po file. Which means, for example, this:

			: <code> msgid "addons_display_a_previous_releases"</code>
			: <code> msgstr "View %d previous releases"</code>

			becomes:

			: <code> msgid "addons_display_a_previous_releases"</code>
			: <code> msgid_plural "addons_display_a_previous_releases"</code>
			: <code> msgstr[0] "View %d previous release"</code>
			: <code> msgstr[1] "View %d previous releases"</code>

			Note that our single and plural forms are the same - that's because we're using placeholder strings.

			The final change comes to the code, instead of calling _(), you'll need to use ngettext():

			: <code>sprintf(ngettext('addons_display_x_comments_total','addons_display_x_comments_total',$total_comments), $total_comments)</code>

			The full gettext manual is [http://www.gnu.org/software/gettext/manual/ available] and intimidating, but it will probably answer any other questions.

	==Dynamic Strings==		==Dynamic Strings==

Twobraids: /* example - fetching values */

2006-12-18T23:23:32Z

example - fetching values

← Older revision		Revision as of 23:23, 18 December 2006
Line 120:		Line 120:
	from ((a left outer join translation as g on a.greeting = g.id and g.locale = 'en-us')		from ((a left outer join translation as g on a.greeting = g.id and g.locale = 'en-us')
	left outer join translation as d on a.greeting = d.id and d.locale = 'en-us')		left outer join translation as d on a.greeting = d.id and d.locale = 'en-us')
			where
			a.id = ''myTargetForFetching''

	+----+----------+----------+		+----+----------+----------+

Twobraids: /* example */

2006-12-18T23:22:01Z

example

@@ Line 94: / Line 94: @@
 * more complicated SQL - enough so to affect preformance?  It depends on how many translations are needed in one query.  I'll start to get worried at six in a single query.
-====example====
+====example - fetching values ====
 translation table
@@ Line 107: / Line 107: @@
   +----+--------+------------------+
-a table
+A table
   +----+----------+----------+
@@ Line 128: / Line 128: @@
 Now there are a couple of problems with this simplified technique.  First, if you have a query that requires ten localized strings, then you need to add ten joins to the query.  Nesting joins that deep make the SQL nearly unreadable.  Second, if a localized string is missing, there is no simple (non-hacky) way to fetch a default value without resorting to another query.
 == Updating locales ==

Twobraids: /* example */

2006-12-18T22:47:24Z

example

← Older revision		Revision as of 22:47, 18 December 2006
Line 118:		Line 118:

	select a.id, g.localized_string as greeting, d.localized_string as danger		select a.id, g.localized_string as greeting, d.localized_string as danger
	from ((a join translation as g on a.greeting = g.id)		from ((a left outer join translation as g on a.greeting = g.id and g.locale = 'en-us')
	join translation as d on a.greeting = d.id)		left outer join translation as d on a.greeting = d.id and d.locale = 'en-us')
	~~where~~
	~~g.locale = 'en-us'~~
	and d.locale = 'en-us';

	+----+----------+----------+		+----+----------+----------+

Wenzel: /* example */ Deutsch :)

2006-12-12T20:21:22Z

example: Deutsch :)

← Older revision		Revision as of 20:21, 12 December 2006
Line 102:		Line 102:
	+----+--------+------------------+		+----+--------+------------------+
	\| 1 \| en-us \| hello \|		\| 1 \| en-us \| hello \|
	\| 1 \| de \| ~~guten tag~~ \|		\| 1 \| de \| Guten Tag \|
	\| 2 \| en-us \| help \|		\| 2 \| en-us \| help \|
	\| 2 \| de \| ~~halp~~ \|		\| 2 \| de \| Hilfe \|
	+----+--------+------------------+		+----+--------+------------------+

Wenzel: /* Updating locales */ execute in order

2006-12-12T20:20:33Z

Updating locales: execute in order

← Older revision		Revision as of 20:20, 12 December 2006
Line 133:		Line 133:

	== Updating locales ==		== Updating locales ==
			These steps are most commonly executed in order.

	=== extracting ===		=== extracting ===
	After l10n strings have been added to the code files/views, they have to be extracted. There's a shell script that goes through the controllers, models and views (.php and .thtml files) and searches for gettext strings. The extracted strings are stored into <code>./messages.po</code> .		After l10n strings have been added to the code files/views, they have to be extracted. There's a shell script that goes through the controllers, models and views (.php and .thtml files) and searches for gettext strings. The extracted strings are stored into <code>./messages.po</code> .

Twobraids: /* Lars Digression */

2006-11-30T06:10:03Z

Lars Digression

← Older revision		Revision as of 06:10, 30 November 2006
Line 75:		Line 75:
	Here are a couple reasons why the translations table schema bothers me. First it is brittle, changing or adding a locale means that the table schema must be altered. Does the code have to be modified to handle a changing schema? Second, the database's referential integrity checking is subverted because the foreign_id column refers to more than one table. I've never seen that kind of feature supported for referential integrity in an RDBMS. That means the referential integrity must be handled externally. The foreign key relationship seems backwards to me.		Here are a couple reasons why the translations table schema bothers me. First it is brittle, changing or adding a locale means that the table schema must be altered. Does the code have to be modified to handle a changing schema? Second, the database's referential integrity checking is subverted because the foreign_id column refers to more than one table. I've never seen that kind of feature supported for referential integrity in an RDBMS. That means the referential integrity must be handled externally. The foreign key relationship seems backwards to me.

	Consider this alternative: make the translations table a simple three column table - a non-unique id, a locale and a string. Together the non-unique id and the locale make up the primary key. For each column in another table that needs a translation, replace that column with a partial key to the translations table id column. Whenever you select a row needing translations from a table, you ~~simple~~ add a join to the translations table using the partial key and the locale.		Consider this alternative: make the translations table a simple three column table - a non-unique id, a locale and a string. Together the non-unique id and the locale make up the primary key. For each column in another table that needs a translation, replace that column with a partial key to the translations table id column. Whenever you select a row needing translations from a table, you simply add a join to the translations table using the partial key and the locale.

	+------------------+------------------+------+-----+---------+-------+		+------------------+------------------+------+-----+---------+-------+

Twobraids: /* cons */

2006-11-30T06:09:12Z

cons

← Older revision		Revision as of 06:09, 30 November 2006
Line 92:		Line 92:
	====cons====		====cons====

	* more complicated SQL - enough so to ~~effect~~ preformance? ~~(shrug)~~		* more complicated SQL - enough so to affect preformance? It depends on how many translations are needed in one query. I'll start to get worried at six in a single query.

	====example====		====example====