| Server IP : 127.0.0.2 / Your IP : 52.14.165.32 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/docs/howto/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?> <!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" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" /> <title>Docutils Internationalization</title> <meta name="author" content="David Goodger" /> <meta name="date" content="2012-01-03" /> <meta name="copyright" content="This document has been placed in the public domain." /> <link rel="stylesheet" href="../../css/html4css1.css" type="text/css" /> </head> <body> <div class="document" id="docutils-internationalization"> <h1 class="title"><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> Internationalization</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Author:</th> <td>David Goodger</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr> <tr><th class="docinfo-name">Date:</th> <td>2012-01-03</td></tr> <tr><th class="docinfo-name">Revision:</th> <td>7302</td></tr> <tr><th class="docinfo-name">Copyright:</th> <td>This document has been placed in the public domain.</td></tr> </tbody> </table> <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#language-module-names" id="id8">Language Module Names</a></li> <li><a class="reference internal" href="#python-code" id="id9">Python Code</a></li> <li><a class="reference internal" href="#docutils-language-module" id="id10">Docutils Language Module</a></li> <li><a class="reference internal" href="#restructuredtext-language-module" id="id11">reStructuredText Language Module</a></li> <li><a class="reference internal" href="#testing-the-language-modules" id="id12">Testing the Language Modules</a></li> <li><a class="reference internal" href="#submitting-the-language-modules" id="id13">Submitting the Language Modules</a></li> </ul> </div> <p>This document describes the internationalization facilities of the <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> project. <a class="reference external" href="http://www.debian.org/doc/manuals/intro-i18n/">Introduction to i18n</a> by Tomohiro KUBOTA is a good general reference. "Internationalization" is often abbreviated as "i18n": "i" + 18 letters + "n".</p> <div class="note"> <p class="first admonition-title">Note</p> <p class="last">The i18n facilities of Docutils should be considered a "first draft". They work so far, but improvements are welcome. Specifically, standard i18n facilities like "gettext" have yet to be explored.</p> </div> <p>Docutils is designed to work flexibly with text in multiple languages (one language at a time). Language-specific features are (or should be <a class="footnote-reference" href="#id2" id="id1">[1]</a>) fully parameterized. To enable a new language, two modules have to be added to the project: one for Docutils itself (the <a class="reference internal" href="#docutils-language-module">Docutils Language Module</a>) and one for the reStructuredText parser (the <a class="reference internal" href="#restructuredtext-language-module">reStructuredText Language Module</a>).</p> <table class="docutils footnote" frame="void" id="id2" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>If anything in Docutils is insufficiently parameterized, it should be considered a bug. Please report bugs to the Docutils project bug tracker on SourceForge at <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&atid=422030">http://sourceforge.net/tracker/?group_id=38414&atid=422030</a>.</td></tr> </tbody> </table> <div class="section" id="language-module-names"> <h1><a class="toc-backref" href="#id8">Language Module Names</a></h1> <p>Language modules are named using <a class="reference external" href="http://www.w3.org/International/articles/language-tags/">language tags</a> as defined in <a class="reference external" href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a>. <a class="footnote-reference" href="#id5" id="id3">[2]</a> in lowercase, converting hyphens to underscores <a class="footnote-reference" href="#id6" id="id4">[3]</a>.</p> <p>A typical language identifier consists of a 2-letter language code from <a class="reference external" href="http://www.loc.gov/standards/iso639-2/php/English_list.php">ISO 639</a> (3-letter codes can be used if no 2-letter code exists). The language identifier can have an optional subtag, typically for variations based on country (from <a class="reference external" href="http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html">ISO 3166</a> 2-letter country codes). If no language identifier is specified, the default is "en" for English. Examples of module names include <tt class="docutils literal">en.py</tt>, <tt class="docutils literal">fr.py</tt>, <tt class="docutils literal">ja.py</tt>, and <tt class="docutils literal">pt_br.py</tt>.</p> <table class="docutils footnote" frame="void" id="id5" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td>BCP stands for 'Best Current Practice', and is a persistent name for a series of RFCs whose numbers change as they are updated. The latest RFC describing language tag syntax is RFC 5646, Tags for the Identification of Languages, and it obsoletes the older RFCs 4646, 3066 and 1766.</td></tr> </tbody> </table> <table class="docutils footnote" frame="void" id="id6" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>Subtags are separated from primary tags by underscores instead of hyphens, to conform to Python naming rules.</td></tr> </tbody> </table> </div> <div class="section" id="python-code"> <h1><a class="toc-backref" href="#id9">Python Code</a></h1> <p>Generally Python code in Docutils is ASCII-only. In language modules, Unicode-escapes can be used for non-ASCII characters.</p> <p><a class="reference external" href="http://www.python.org/peps/pep-0263.html">PEP 263</a> introduces source code encodings to Python modules, implemented beginning in Python 2.3. Especially for languages with non-Latin scripts, using UTF-8 encoded literal Unicode strings increases the readability. Start the source code file with the magic comment:</p> <pre class="literal-block"> # -*- coding: utf-8 -*- </pre> <p>As mentioned in the note above, developers are invited to explore "gettext" and other i18n technologies.</p> </div> <div class="section" id="docutils-language-module"> <h1><a class="toc-backref" href="#id10">Docutils Language Module</a></h1> <p>Modules in <tt class="docutils literal">docutils/languages</tt> contain language mappings for markup-independent language-specific features of Docutils. To make a new language module, just copy the <tt class="docutils literal">en.py</tt> file, rename it with the code for your language (see <a class="reference internal" href="#language-module-names">Language Module Names</a> above), and translate the terms as described below.</p> <p>Each Docutils language module contains three module attributes:</p> <dl class="docutils"> <dt><tt class="docutils literal">labels</tt></dt> <dd><p class="first">This is a mapping of node class names to language-dependent boilerplate label text. The label text is used by Writer components when they encounter document tree elements whose class names are the mapping keys.</p> <p class="last">The entry values (<em>not</em> the keys) should be translated to the target language.</p> </dd> <dt><tt class="docutils literal">bibliographic_fields</tt></dt> <dd><p class="first">This is a mapping of language-dependent field names (converted to lower case) to canonical field names (keys of <tt class="docutils literal">DocInfo.biblio_notes</tt> in <tt class="docutils literal">docutils.transforms.frontmatter</tt>). It is used when transforming bibliographic fields.</p> <p class="last">The keys should be translated to the target language.</p> </dd> <dt><tt class="docutils literal">author_separators</tt></dt> <dd><p class="first">This is a list of strings used to parse the 'Authors' bibliographic field. They separate individual authors' names, and are tried in order (i.e., earlier items take priority, and the first item that matches wins). The English-language module defines them as <tt class="docutils literal"><span class="pre">[';',</span> <span class="pre">',']</span></tt>; semi-colons can be used to separate names like "Arthur Pewtie, Esq.".</p> <p class="last">Most languages won't have to "translate" this list.</p> </dd> </dl> </div> <div class="section" id="restructuredtext-language-module"> <h1><a class="toc-backref" href="#id11">reStructuredText Language Module</a></h1> <p>Modules in <tt class="docutils literal">docutils/parsers/rst/languages</tt> contain language mappings for language-specific features of the reStructuredText parser. To make a new language module, just copy the <tt class="docutils literal">en.py</tt> file, rename it with the code for your language (see <a class="reference internal" href="#language-module-names">Language Module Names</a> above), and translate the terms as described below.</p> <p>Each reStructuredText language module contains two module attributes:</p> <dl class="docutils"> <dt><tt class="docutils literal">directives</tt></dt> <dd><p class="first">This is a mapping from language-dependent directive names to canonical directive names. The canonical directive names are registered in <tt class="docutils literal">docutils/parsers/rst/directives/__init__.py</tt>, in <tt class="docutils literal">_directive_registry</tt>.</p> <p class="last">The keys should be translated to the target language. Synonyms (multiple keys with the same values) are allowed; this is useful for abbreviations.</p> </dd> <dt><tt class="docutils literal">roles</tt></dt> <dd><p class="first">This is a mapping language-dependent role names to canonical role names for interpreted text. The canonical directive names are registered in <tt class="docutils literal">docutils/parsers/rst/states.py</tt>, in <tt class="docutils literal">Inliner._interpreted_roles</tt> (this may change).</p> <p class="last">The keys should be translated to the target language. Synonyms (multiple keys with the same values) are allowed; this is useful for abbreviations.</p> </dd> </dl> </div> <div class="section" id="testing-the-language-modules"> <h1><a class="toc-backref" href="#id12">Testing the Language Modules</a></h1> <p>Whenever a new language module is added or an existing one modified, the unit tests should be run. The test modules can be found in the docutils/test directory from <a class="reference external" href="http://sourceforge.net/cvs/?group_id=38414">CVS</a> or from the <a class="reference external" href="http://docutils.sf.net/docutils-snapshot.tgz">latest CVS snapshot</a>.</p> <p>The <tt class="docutils literal">test_language.py</tt> module can be run as a script. With no arguments, it will test all language modules. With one or more language codes, it will test just those languages. For example:</p> <pre class="literal-block"> $ python test_language.py en .. ---------------------------------------- Ran 2 tests in 0.095s OK </pre> <p>Use the "alltests.py" script to run all test modules, exhaustively testing the parser and other parts of the Docutils system.</p> </div> <div class="section" id="submitting-the-language-modules"> <h1><a class="toc-backref" href="#id13">Submitting the Language Modules</a></h1> <p>If you do not have repository write access and want to contribute your language modules, feel free to submit them via the <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&atid=422032">SourceForge patch tracker</a>.</p> </div> </div> </body> </html>