<?xml version="1.0" encoding="utf-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Localization</title> <link rel="stylesheet" type="text/css" href="styles.css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /> <style type="text/css"> body { background-image: url('images/draft.png'); background-repeat: no-repeat; background-position: top left; /* The following properties make the watermark "fixed" on the page. */ /* I think that's just a bit too distracting for the reader... */ /* background-attachment: fixed; */ /* background-position: center center; */ }</style> <link rel="home" href="index.html" title="Version Control with Subversion [DRAFT]" /> <link rel="up" href="svn.customization.html" title="Chapter 7. Customizing Your Subversion Experience" /> <link rel="prev" href="svn.advanced.confarea.html" title="Runtime Configuration Area" /> <link rel="next" href="svn.advanced.externaleditors.html" title="Using External Editors" /> </head> <body> <div xmlns="" id="vcws-version-notice"> <p>This text is a work in progress—highly subject to change—and may not accurately describe any released version of the Apache™ Subversion® software. Bookmarking or otherwise referring others to this page is probably not such a smart idea. Please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a> for stable versions of this book.</p> </div> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Localization</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="svn.advanced.confarea.html">Prev</a> </td> <th width="60%" align="center">Chapter 7. Customizing Your Subversion Experience</th> <td width="20%" align="right"> <a accesskey="n" href="svn.advanced.externaleditors.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1" title="Localization"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="svn.advanced.l10n"></a>Localization</h2> </div> </div> </div> <p> <a id="idp18638192" class="indexterm"></a><em class="firstterm">Localization</em> 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 <em class="firstterm">localized</em>. This section describes steps Subversion has made toward localization.</p> <div class="sect2" title="Understanding Locales"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.advanced.l10n.understanding"></a>Understanding Locales</h3> </div> </div> </div> <p>Most modern operating systems have a notion of the <span class="quote">“<span class="quote">current locale</span>”</span>—that is, the region or country whose localization conventions are honored. These conventions—typically chosen by some runtime configuration mechanism on the computer—affect the way in which programs present data to the user, as well as the way in which they accept user input.</p> <p>On most Unix-like systems, you can check the values of the locale-related runtime configuration options by running the <span class="command"><strong>locale</strong></span> command:</p> <div class="informalexample"> <pre class="screen"> $ locale LANG= LC_COLLATE="C" LC_CTYPE="C" LC_MESSAGES="C" LC_MONETARY="C" LC_NUMERIC="C" LC_TIME="C" LC_ALL="C" $ </pre> </div> <p>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 <code class="literal">C</code> locale, but users can set these variables to specific country/language code combinations. For example, if one were to set the <code class="literal">LC_TIME</code> variable to <code class="literal">fr_CA</code>, programs would know to present time and date information formatted according to a French-speaking Canadian's expectations. And if one were to set the <code class="literal">LC_MESSAGES</code> variable to <code class="literal">zh_TW</code>, programs would know to present human-readable messages in Traditional Chinese. Setting the <code class="literal">LC_ALL</code> variable has the effect of changing every locale variable to the same value. The value of <code class="literal">LANG</code> is used as a default value for any locale variable that is unset. To see the list of available locales on a Unix system, run the command <strong class="userinput"><code>locale -a</code></strong>.</p> <p>On Windows, locale configuration is done via the <span class="quote">“<span class="quote">Regional and Language Options</span>”</span> control panel item. There you can view and select the values of individual settings from the available locales, and even customize (at a sickening level of detail) several of the display formatting conventions.</p> </div> <div class="sect2" title="Subversion's Use of Locales"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="svn.advanced.l10n.svnuse"></a>Subversion's Use of Locales</h3> </div> </div> </div> <p>The Subversion client, <span class="command"><strong>svn</strong></span>, honors the current locale configuration in two ways. First, it notices the value of the <code class="literal">LC_MESSAGES</code> variable and attempts to print all messages in the specified language. For example:</p> <div class="informalexample"> <pre class="screen"> $ export LC_MESSAGES=de_DE $ svn help cat cat: Gibt den Inhalt der angegebenen Dateien oder URLs aus. Aufruf: cat ZIEL[@REV]... … </pre> </div> <p>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 gettext package, which results in translation modules that end with the <code class="filename">.mo</code> filename extension. For example, the German translation file is named <code class="filename">de.mo</code>. These translation files are installed somewhere on your system. On Unix, they typically live in <code class="filename">/usr/share/locale/</code>, while on Windows they're often found in the <code class="filename">share\locale\</code> folder in Subversion's installation area. Once installed, a module is named after the program for which it provides translations. For example, the <code class="filename">de.mo</code> file may ultimately end up installed as <code class="filename">/usr/share/locale/de/LC_MESSAGES/subversion.mo</code>. By browsing the installed <code class="filename">.mo</code> files, you can see which languages the Subversion client is able to speak.</p> <p> <a id="idp18665264" class="indexterm"></a> <a id="idp18666336" class="indexterm"></a>The second way in which the locale is honored involves how <span class="command"><strong>svn</strong></span> interprets your input. The repository stores all paths, filenames, and log messages in Unicode, encoded as UTF-8. In that sense, the repository is <em class="firstterm">internationalized</em>—that is, the repository is ready to accept input in any human language. This means, however, that the Subversion client is responsible for sending only UTF-8 filenames and log messages into the repository. To do this, it must convert the data from the native locale into UTF-8.</p> <p>For example, suppose you create a file named <code class="filename">caffè.txt</code>, and then when committing the file, you write the log message as <span class="quote">“<span class="quote">Adesso il caffè è più forte.</span>”</span> Both the filename and the log message contain non-ASCII characters, but because your locale is set to <code class="literal">it_IT</code>, the Subversion client knows to interpret them as Italian. It uses an Italian character set to convert the data to UTF-8 before sending it off to the repository.</p> <p>Note that while the repository demands UTF-8 filenames and log messages, it <span class="emphasis"><em>does not</em></span> 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.</p> <div class="sidebar" title="Character Set Conversion Errors"> <div class="titlepage"> <div> <div> <p class="title"> <strong>Character Set Conversion Errors</strong> </p> </div> </div> </div> <p>While using Subversion, you might get hit with an error related to character set conversions:</p> <div class="informalexample"> <pre class="screen"> svn: E000022: Can't convert string from native encoding to 'UTF-8': … svn: E000022: Can't convert string from 'UTF-8' to native encoding: … </pre> </div> <p>Errors such as this typically occur when the Subversion client has received a UTF-8 string from the repository, but not all of the characters in that string can be represented using the encoding of the current locale. For example, if your locale is <code class="literal">en_US</code> but a collaborator has committed a Japanese filename, you're likely to see this error when you receive the file during an <span class="command"><strong>svn update</strong></span>.</p> <p>The solution is either to set your locale to something that <span class="emphasis"><em>can</em></span> 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.)</p> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="svn.advanced.confarea.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="svn.customization.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="svn.advanced.externaleditors.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Runtime Configuration Area </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Using External Editors</td> </tr> </table> </div> <div xmlns="" id="vcws-footer"> <hr /> <img src="images/cc-by.png" style="float: right;" /> <p>You are reading <em>Version Control with Subversion</em> (for Subversion 1.8), by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato.</p> <p>This work is licensed under the <a href="http://creativecommons.org/licenses/by/2.0/">Creative Commons Attribution License v2.0</a>.</p> <p>To submit comments, corrections, or other contributions to the text, please visit <a href="http://www.svnbook.com/">http://www.svnbook.com/</a>.</p> </div> </body> </html>