diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:15:05 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:15:05 +0000 |
| commit | 46651ce6fe013220ed397add242004d764fc0153 (patch) | |
| tree | 6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/html/nls-programmer.html | |
| parent | Initial commit. (diff) | |
| download | postgresql-14-upstream.tar.xz postgresql-14-upstream.zip | |
Adding upstream version 14.5.upstream/14.5upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/html/nls-programmer.html')
| -rw-r--r-- | doc/src/sgml/html/nls-programmer.html | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/doc/src/sgml/html/nls-programmer.html b/doc/src/sgml/html/nls-programmer.html new file mode 100644 index 0000000..7595b71 --- /dev/null +++ b/doc/src/sgml/html/nls-programmer.html @@ -0,0 +1,154 @@ +<?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>55.2. For the Programmer</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="nls-translator.html" title="55.1. For the Translator" /><link rel="next" href="plhandler.html" title="Chapter 56. Writing a Procedural Language Handler" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.2. For the Programmer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-translator.html" title="55.1. For the Translator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="nls.html" title="Chapter 55. Native Language Support">Up</a></td><th width="60%" align="center">Chapter 55. Native Language Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 56. Writing a Procedural Language Handler">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="NLS-PROGRAMMER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.2. For the Programmer</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="nls-programmer.html#NLS-MECHANICS">55.2.1. Mechanics</a></span></dt><dt><span class="sect2"><a href="nls-programmer.html#NLS-GUIDELINES">55.2.2. Message-Writing Guidelines</a></span></dt></dl></div><div class="sect2" id="NLS-MECHANICS"><div class="titlepage"><div><div><h3 class="title">55.2.1. Mechanics</h3></div></div></div><p> + This section describes how to implement native language support in a + program or library that is part of the + <span class="productname">PostgreSQL</span> distribution. + Currently, it only applies to C programs. + </p><div class="procedure" id="id-1.10.7.3.2.3"><p class="title"><strong>Adding NLS Support to a Program</strong></p><ol class="procedure" type="1"><li class="step"><p> + Insert this code into the start-up sequence of the program: +</p><pre class="programlisting"> +#ifdef ENABLE_NLS +#include <locale.h> +#endif + +... + +#ifdef ENABLE_NLS +setlocale(LC_ALL, ""); +bindtextdomain("<em class="replaceable"><code>progname</code></em>", LOCALEDIR); +textdomain("<em class="replaceable"><code>progname</code></em>"); +#endif +</pre><p> + (The <em class="replaceable"><code>progname</code></em> can actually be chosen + freely.) + </p></li><li class="step"><p> + Wherever a message that is a candidate for translation is found, + a call to <code class="function">gettext()</code> needs to be inserted. E.g.: +</p><pre class="programlisting"> +fprintf(stderr, "panic level %d\n", lvl); +</pre><p> + would be changed to: +</p><pre class="programlisting"> +fprintf(stderr, gettext("panic level %d\n"), lvl); +</pre><p> + (<code class="symbol">gettext</code> is defined as a no-op if NLS support is + not configured.) + </p><p> + This tends to add a lot of clutter. One common shortcut is to use: +</p><pre class="programlisting"> +#define _(x) gettext(x) +</pre><p> + Another solution is feasible if the program does much of its + communication through one or a few functions, such as + <code class="function">ereport()</code> in the backend. Then you make this + function call <code class="function">gettext</code> internally on all + input strings. + </p></li><li class="step"><p> + Add a file <code class="filename">nls.mk</code> in the directory with the + program sources. This file will be read as a makefile. The + following variable assignments need to be made here: + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">CATALOG_NAME</code></span></dt><dd><p> + The program name, as provided in the + <code class="function">textdomain()</code> call. + </p></dd><dt><span class="term"><code class="varname">AVAIL_LANGUAGES</code></span></dt><dd><p> + List of provided translations — initially empty. + </p></dd><dt><span class="term"><code class="varname">GETTEXT_FILES</code></span></dt><dd><p> + List of files that contain translatable strings, i.e., those + marked with <code class="function">gettext</code> or an alternative + solution. Eventually, this will include nearly all source + files of the program. If this list gets too long you can + make the first <span class="quote">“<span class="quote">file</span>”</span> be a <code class="literal">+</code> + and the second word be a file that contains one file name per + line. + </p></dd><dt><span class="term"><code class="varname">GETTEXT_TRIGGERS</code></span></dt><dd><p> + The tools that generate message catalogs for the translators + to work on need to know what function calls contain + translatable strings. By default, only + <code class="function">gettext()</code> calls are known. If you used + <code class="function">_</code> or other identifiers you need to list + them here. If the translatable string is not the first + argument, the item needs to be of the form + <code class="literal">func:2</code> (for the second argument). + If you have a function that supports pluralized messages, + the item should look like <code class="literal">func:1,2</code> + (identifying the singular and plural message arguments). + </p></dd></dl></div><p> + </p></li></ol></div><p> + The build system will automatically take care of building and + installing the message catalogs. + </p></div><div class="sect2" id="NLS-GUIDELINES"><div class="titlepage"><div><div><h3 class="title">55.2.2. Message-Writing Guidelines</h3></div></div></div><p> + Here are some guidelines for writing messages that are easily + translatable. + + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + Do not construct sentences at run-time, like: +</p><pre class="programlisting"> +printf("Files were %s.\n", flag ? "copied" : "removed"); +</pre><p> + The word order within the sentence might be different in other + languages. Also, even if you remember to call <code class="function">gettext()</code> on + each fragment, the fragments might not translate well separately. It's + better to duplicate a little code so that each message to be + translated is a coherent whole. Only numbers, file names, and + such-like run-time variables should be inserted at run time into + a message text. + </p></li><li class="listitem"><p> + For similar reasons, this won't work: +</p><pre class="programlisting"> +printf("copied %d file%s", n, n!=1 ? "s" : ""); +</pre><p> + because it assumes how the plural is formed. If you figured you + could solve it like this: +</p><pre class="programlisting"> +if (n==1) + printf("copied 1 file"); +else + printf("copied %d files", n): +</pre><p> + then be disappointed. Some languages have more than two forms, + with some peculiar rules. It's often best to design the message + to avoid the issue altogether, for instance like this: +</p><pre class="programlisting"> +printf("number of copied files: %d", n); +</pre><p> + </p><p> + If you really want to construct a properly pluralized message, + there is support for this, but it's a bit awkward. When generating + a primary or detail error message in <code class="function">ereport()</code>, you can + write something like this: +</p><pre class="programlisting"> +errmsg_plural("copied %d file", + "copied %d files", + n, + n) +</pre><p> + The first argument is the format string appropriate for English + singular form, the second is the format string appropriate for + English plural form, and the third is the integer control value + that determines which plural form to use. Subsequent arguments + are formatted per the format string as usual. (Normally, the + pluralization control value will also be one of the values to be + formatted, so it has to be written twice.) In English it only + matters whether <em class="replaceable"><code>n</code></em> is 1 or not 1, but in other + languages there can be many different plural forms. The translator + sees the two English forms as a group and has the opportunity to + supply multiple substitute strings, with the appropriate one being + selected based on the run-time value of <em class="replaceable"><code>n</code></em>. + </p><p> + If you need to pluralize a message that isn't going directly to an + <code class="function">errmsg</code> or <code class="function">errdetail</code> report, you have to use + the underlying function <code class="function">ngettext</code>. See the gettext + documentation. + </p></li><li class="listitem"><p> + If you want to communicate something to the translator, such as + about how a message is intended to line up with other output, + precede the occurrence of the string with a comment that starts + with <code class="literal">translator</code>, e.g.: +</p><pre class="programlisting"> +/* translator: This message is not what it seems to be. */ +</pre><p> + These comments are copied to the message catalog files so that + the translators can see them. + </p></li></ul></div><p> + </p></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls-translator.html" title="55.1. For the Translator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="nls.html" title="Chapter 55. Native Language Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 56. Writing a Procedural Language Handler">Next</a></td></tr><tr><td width="40%" align="left" valign="top">55.1. For the Translator </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 56. Writing a Procedural Language Handler</td></tr></table></div></body></html>
\ No newline at end of file |