[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

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 @@
+  <!-- ******************************************************************* -->
+  <!-- *** 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
+      <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...
+      <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>

More information about the svnbook-dev mailing list