[svnbook commit] r1330 - in trunk/src/en: . book
sussman
svnbook-dev at red-bean.com
Tue May 24 20:16:42 CDT 2005
Author: sussman
Date: Tue May 24 20:16:41 2005
New Revision: 1330
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch07.xml
Log:
Document subversion's use of locale.
* src/en/book/ch07.xml: new "Localization" section.
* src/en/book/TODO: remove item.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Tue May 24 20:16:41 2005
@@ -8,10 +8,6 @@
* Chapter 8 Section 1.1 "Repository Layer" documents the pre-FSFS state
of affairs. [MIKE]
- * Need whole new section explaining activating l10n (LOCALE=) for
- message translations. This probably needs to be an "advanced
- topics" chapter 7 section. [BEN]
-
* Chapter 2's "Repository URLs" sidebar should shrink back to
nothing but the schema-table, with a xref to a new Chapter 7
section. The new chapter 7 section is all about repository URL
Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml (original)
+++ trunk/src/en/book/ch07.xml Tue May 24 20:16:41 2005
@@ -2476,6 +2476,165 @@
</sect2>
</sect1>
+ <!-- ******************************************************************* -->
+ <!-- *** SECTION 5: LOCALIZATION *** -->
+ <!-- ******************************************************************* -->
+ <sect1 id="svn-ch-7-sect-5">
+ <title>Localization</title>
+
+ <para><firstterm>Localization</firstterm> is the act of making
+ programs behave in a region-specific way. When a program
+ formats numbers or dates in a way specific to your part of the
+ world, or prints messages (or accepts input) in your native
+ language, the program is said to
+ be <firstterm>localized</firstterm>.</para>
+
+ <sect2 id="svn-ch7-sect-5.1">
+ <title>Understanding locales</title>
+
+ <para>Most modern operating systems have a notion
+ of <quote>current locale</quote>—that is, the current
+ region or country that the computer is located in. The value
+ of the locale affects the way in which programs present data
+ to the user, as well as the way in which they accept user
+ input.</para>
+
+ <para>On Unix-like systems, the value of the current locale can
+ be seen by running the <command>locale</command>
+ command:</para>
+
+ <screen>
+$ locale
+LANG=
+LC_COLLATE="C"
+LC_CTYPE="C"
+LC_MESSAGES="C"
+LC_MONETARY="C"
+LC_NUMERIC="C"
+LC_TIME="C"
+LC_ALL="C"
+</screen>
+
+ <para>The output is a list of locale-related environment
+ variables and their current values. In this example, the
+ variables are all set to the default <literal>C</literal>
+ locale, but users can set these variables to specific
+ country/language code combinations. For example, if one were
+ to set the <literal>LC_TIME</literal> variable
+ to <literal>fr_CA</literal>, then programs would know to
+ present time and date information formatted according a
+ French-speaking Canadian's expectations. And if one were to
+ set the <literal>LC_MESSAGES</literal> variable
+ to <literal>zh_TW</literal>, then programs would know to
+ present human-readable messages in Traditional Chinese.</para>
+
+ <para>Setting the <literal>LC_ALL</literal> variable has the
+ effect of changing every locale variable to the same value.
+ The value of <literal>LANG</literal> is used as a default
+ value for any locale variable that is unset.</para>
+
+ <para>To see the list of available locales on a Unix system, run
+ the command <command>locale -a</command>. On Windows, one can
+ open the <quote>Regional and Language Options</quote> control
+ panel to view and select available locales.</para>
+
+ </sect2>
+
+ <sect2 id="svn-ch7-sect-5.2">
+ <title>Subversion's use of locales</title>
+
+ <para>The Subversion client, <command>svn</command>, makes use
+ of the current locale in two ways. First, it notices the
+ value of the <literal>LC_MESSAGES</literal> variable and
+ attempts to print all messages in the specified language. For
+ example:</para>
+
+ <screen>
+$ export LC_MESSAGES=de_DE
+$ svn help cat
+cat: Ausgabe des Inhaltes der angegebenen Dateien oder URLs
+Aufruf: cat ZIEL...
+[...]
+</screen>
+
+ <para>This behavior works identically on both Unix and Windows
+ systems. Note, though, that while your operating system might
+ have support for a certain locale, the Subversion client still
+ may not be able to speak the particular language. In order to
+ produce localized messages, human volunteers must provide
+ translations for each language. The translations are written
+ using the GNU <command>gettext</command> package, which
+ results in translation <quote>modules</quote> that end
+ with <filename>.mo</filename> extensions. For example, the
+ German translation file is named <filename>de.mo</filename>.
+ These translation files are installed somewhere on your
+ system. On Unix, they typically live
+ in <filename>/usr/local/share/locale/</filename>, while on
+ Windows they're often found in
+ the <filename>\share\locale\</filename> folder in Subversion's
+ installation area. Once installed, a module is named after
+ the program it provides translations for. For example,
+ the <filename>de.mo</filename> file may ultimately end up
+ installed
+ as <filename>/usr/local/share/locale/de/LC_MESSAGES/subversion.mo</filename>.
+ By browsing the installed <filename>.mo</filename> files, you
+ can see which languages the Subversion client is able to
+ speak.</para>
+
+ <para>The second way in which locale is important is that it
+ tells the <command>svn</command> program how to interpret your
+ input. The repository stores all paths, filenames, and log
+ messages in Unicode. In that sense, the repository
+ is <firstterm>internationalized</firstterm>— that is,
+ the repository is ready to accept input in any human language.
+ The repository stores the Unicode data as UTF-8, which is a
+ particular encoding of Unicode. This means, however, that the
+ Subversion client is responsible for sending only UTF-8
+ filenames and log messages into the repository. In order to
+ do this, it must convert the data from the native locale into
+ UTF-8.</para>
+
+ <para>For example, suppose you create a file
+ named<filename>caffè.txt</filename>, and then when committing
+ the file, you write the log message as <quote>Adesso il caffè
+ è più forte</quote>. Both the filename and log message
+ contain non-ASCII characters, but because your locale is set
+ to <literal>it_IT</literal>, the Subversion client knows to
+ interpret them as Italian. It uses an Italian character set
+ to convert the data to UTF-8 before sending them off to the
+ repository.</para>
+
+ <para>Note that while the repository demands UTF-8 filenames and
+ log messages, it <emphasis>does not</emphasis> pay attention
+ to file contents. Subversion treats file contents as opaque
+ strings of bytes, and neither client nor server makes an
+ attempt to understand the character set or encoding of the
+ contents.</para>
+
+ <sidebar>
+ <title>"Error: can't recode string"</title>
+
+ <para>Are you seeing this error? It means that the Subversion
+ client has received a UTF-8 string from the repository, but
+ the characters can't be converted to the current locale.
+ For example, if your locale is <literal>en_US</literal> but
+ a collaborator has committed a Japanese filename, you're
+ likely to see this error when you receive the file during
+ an <command>svn update</command>.</para>
+
+ <para>The solution is either to set your locale to something
+ which <emphasis>can</emphasis> represent the incoming UTF-8
+ data, or to change the filename or log message in the
+ repository. (And don't forget to slap your collaborator's
+ hand; projects should decide on common languages ahead of
+ time, so that all participants are using the same
+ locale.)</para>
+ </sidebar>
+
+ </sect2>
+
+ </sect1>
+
</chapter>
<!--
More information about the svnbook-dev
mailing list