Add Japanese translation

We rely on python sphinx-intl to handle the translation, using standard .pot /
.po translation files.

The following steps are required each time the translation needs to be updated:

make gettext
sphinx-intl update -p _build/gettext -l ja

Translators can then work on the various .po files generated (or updated) in
docs/locale/ja/LC_MESSAGES/, and the translated documentation can be built
using:

make -e SPHINXOPTS="-D language='ja'" html

Once everything is ok, simply commit the modified files in docs/locale.  Note
that we don't track the .pot files, generated in docs/_build/gettext/.

Pull request #125, fixes #123

Backpatch-through: 14
Reviewed-by: Michael Paquier

.gitignore

@@ -16,3 +16,4 @@ regression.*
 
 # Documentation artifacts
 docs/_build
+docs/locale/**/*.mo

docs/README

@@ -11,7 +11,7 @@ Note that while markdown is more readable as raw text, it's a way simpler
 syntax that lacks a lot of features that reStructuredText offers.  Relying on
 sphinx gives us an opportunity to later write parts of the documentation in
 reStructuredText if needed, but also offers other appealing features like
-multilingual documentation that we may reintroduce in a near future.
+multilingual documentation.
 
 Readthedocs is the expected target, so use its theme and follow its
 recommendation about pinning various requirement versions.
@@ -35,7 +35,34 @@ update the docs/requirements.in and generate the target docs/requirements.txt
 using pip-compile.  See the link about this tool below for more details on how
 to use it.
 
-As a first step, simply duplicate the README.md for the documentation.
+Translation
+-----------
+
+Note that each translator has to follow all those steps whenever the
+translation needs to be updated.  Note also that those commands assume that the
+current working directory is docs/.
+
+- Bootstrapping the translation (the .pot files) is simply done using
+
+make gettext
+
+This will generate the various .pot file in _build/gettext.
+
+- The per-language translation files (the .po files) can then be generated.  We
+  currently only support Japanese, the rest of the commands will assume a
+  single Japanese translation.  Those files can be generated using:
+
+sphinx-intl update -p _build/gettext -l ja
+
+The files are generated (or updated) in the docs/locale/ja/LC_MESSAGES/.
+
+- You can then translate the .po file with any editor (poedit, vim...)
+
+- The translated documentation can be built using:
+
+make -e SPHINXOPTS="-D language='ja'" html
+
+- If everything is ok, you can commit the modifications in the .po files.
 
 References
 ----------
@@ -47,3 +74,6 @@ References if you're interested in the various design choices:
 - myst parser: https://myst-parser.readthedocs.io
 - pip-tools / pip-compile: https://pip-tools.readthedocs.io
 - RTD sphinx theme: https://sphinx-rtd-theme.readthedocs.io
+- Internationalization:
+  https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
+  https://docs.readthedocs.io/en/stable/localization.html#projects-with-multiple-translations-sphinx-only

docs/conf.py

@@ -25,3 +25,11 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+
+# Internationalization
+# https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
+# https://docs.readthedocs.io/en/stable/guides/manage-translations-sphinx.html
+
+locale_dirs = ['locale/']   # path is example but recommended.
+gettext_compact = False     # optional.
+gettext_uuid = True         # optional.

docs/locale/ja/LC_MESSAGES/description.po

@@ -0,0 +1,46 @@
+# LANGUAGE message translation file for pg_hint_plan description.
+# Copyright (C) 2012-2023, NIPPON TELEGRAPH AND TELEPHONE CORPORATION
+# This file is distributed under the same license as the pg_hint_plan
+# package.
+# Julien Rouhaud <[email protected]>, 2023.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pg_hint_plan \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-03-02 12:25+0800\n"
+"PO-Revision-Date: 2023-03-02 12:28+0800\n"
+"Last-Translator: Julien Rouhaud <[email protected]>\n"
+"Language: ja\n"
+"Language-Team: ja <[email protected]>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.12.1\n"
+
+#: ../../description.md:1 36ecf3f5b33149abba3c29147babecec
+msgid "Description"
+msgstr "機能説明"
+
+#: ../../description.md:3 876c61bdb07540eaac5fa67254a8b6d0
+msgid "Basic Usage"
+msgstr "ヒントの指定方法"
+
+#: ../../description.md:5 da1244d0fca640da9c0728a3d004e462
+msgid ""
+"`pg_hint_plan` reads hinting phrases in a comment of special form given "
+"with the target SQL statement. The special form is beginning by the "
+"character sequence `\"/\\*+\"` and ends with `\"\\*/\"`. Hint phrases are"
+" consists of hint name and following parameters enclosed by parentheses "
+"and delimited by spaces. Each hinting phrases can be delimited by new "
+"lines for readability."
+msgstr ""
+
+#: ../../description.md:11 f580a4b229054382a573c06093f5a37e
+msgid ""
+"In the example below, hash join is selected as the joining method and "
+"scanning `pgbench_accounts` by sequential scan method."
+msgstr ""
+

docs/locale/ja/LC_MESSAGES/errors.po

@@ -0,0 +1,78 @@
+# LANGUAGE message translation file for pg_hint_plan errors.
+# Copyright (C) 2012-2023, NIPPON TELEGRAPH AND TELEPHONE CORPORATION
+# This file is distributed under the same license as the pg_hint_plan
+# package.
+# Julien Rouhaud <[email protected]>, 2023.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pg_hint_plan \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-03-02 12:25+0800\n"
+"PO-Revision-Date: 2023-03-02 12:28+0800\n"
+"Last-Translator: Julien Rouhaud <[email protected]>\n"
+"Language: ja\n"
+"Language-Team: ja <[email protected]>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.12.1\n"
+
+#: ../../errors.md:1 7a1ddc938c2e4eff8e46c6d3a9d7b320
+msgid "Errors"
+msgstr ""
+
+#: ../../errors.md:3 2ad9c694dc1f464a9658fdad13822941
+msgid ""
+"`pg_hint_plan` stops parsing on any error and uses hints already parsed "
+"on the most cases. Following are the typical errors."
+msgstr ""
+
+#: ../../errors.md:6 32c4a156d0224a2cb1360639c163f808
+msgid "Syntax errors"
+msgstr ""
+
+#: ../../errors.md:8 3fa7aacd17aa43f1b1b07c5ae6df1de7
+msgid ""
+"Any syntactical errors or wrong hint names are reported as a syntax "
+"error. These errors are reported in the server log with the message level"
+" specified by `pg_hint_plan.message_level` if `pg_hint_plan.debug_print` "
+"is on and above."
+msgstr ""
+
+#: ../../errors.md:12 41877d1989c6485cbea38eb7994fdf43
+msgid "Object misspecifications"
+msgstr ""
+
+#: ../../errors.md:14 74af48e14c8a47eaaaf84bb0773c28e3
+msgid ""
+"Object misspecifications result in silent ignorance of the hints. This "
+"kind of error is reported as \"not used hints\" in the server log by the "
+"same condition as syntax errors."
+msgstr ""
+
+#: ../../errors.md:18 36e56d95d7714a399d93f072d0df67bf
+msgid "Redundant or conflicting hints"
+msgstr ""
+
+#: ../../errors.md:20 dd9d92795ba843f998946bedb601ad2b
+msgid ""
+"The last hint will be active when redundant hints or hints conflicting "
+"with each other. This kind of error is reported as \"duplication hints\" "
+"in the server log by the same condition to syntax errors."
+msgstr ""
+
+#: ../../errors.md:24 55fe2ef2e9f2495a9d52f7beff0ac626
+msgid "Nested comments"
+msgstr ""
+
+#: ../../errors.md:26 2c875a3235cd45f79ab11d50bec13031
+msgid ""
+"Hint comment cannot include another block comment within. If "
+"`pg_hint_plan` finds it, differently from other erros, it stops parsing "
+"and abandans all hints already parsed. This kind of error is reported in "
+"the same manner as other errors."
+msgstr ""
+

docs/locale/ja/LC_MESSAGES/functional_limitations.po

@@ -0,0 +1,82 @@
+# LANGUAGE message translation file for pg_hint_plan functional limitations.
+# Copyright (C) 2012-2023, NIPPON TELEGRAPH AND TELEPHONE CORPORATION
+# This file is distributed under the same license as the pg_hint_plan
+# package.
+# Julien Rouhaud <[email protected]>, 2023.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: pg_hint_plan \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2023-03-02 12:25+0800\n"
+"PO-Revision-Date: 2023-03-02 12:28+0800\n"
+"Last-Translator: Julien Rouhaud <[email protected]>\n"
+"Language: ja\n"
+"Language-Team: ja <[email protected]>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.12.1\n"
+
+#: ../../functional_limitations.md:1 cc8b677c2cb549fa929dcd81006fa487
+msgid "Functional limitations"
+msgstr ""
+
+#: ../../functional_limitations.md:3 53469c44e28446319def9d32da932fc3
+msgid "Influences of some of planner GUC parameters"
+msgstr ""
+
+#: ../../functional_limitations.md:5 17f0b27352c74f64bd6dd3387e841833
+msgid ""
+"The planner does not try to consider joining order for FROM clause "
+"entries more than `from_collapse_limit`. `pg_hint_plan` cannot affect "
+"joining order as expected for the case."
+msgstr ""
+
+#: ../../functional_limitations.md:9 465e0f7dc3204efb9f269b42a2a20a03
+msgid "Hints trying to enforce unexecutable plans"
+msgstr ""
+
+#: ../../functional_limitations.md:11 08c0cb232704464e8bf0fd2fb8ba0499
+msgid ""
+"Planner chooses any executable plans when the enforced plan cannot be "
+"executed."
+msgstr ""
+
+#: ../../functional_limitations.md:13 ed572c8c6d0b4c70936aee5225ca826f
+msgid "`FULL OUTER JOIN` to use nested loop"
+msgstr ""
+
+#: ../../functional_limitations.md:14 cdcca136c9a648ec8081891c39b29ea5
+msgid "To use indexes that does not have columns used in quals"
+msgstr ""
+
+#: ../../functional_limitations.md:15 edf44a241d39485fb81d66b4c1b7fbc2
+msgid "To do TID scans for queries without ctid conditions"
+msgstr ""
+
+#: ../../functional_limitations.md:17 1e02a948684f4eb69172f27fd8b5e361
+msgid "Queries in ECPG"
+msgstr ""
+
+#: ../../functional_limitations.md:19 5c0c4a6a4f8449e5ba4d7029785bb68b
+msgid ""
+"ECPG removes comments in queries written as embedded SQLs so hints cannot"
+" be passed form those queries. The only exception is that `EXECUTE` "
+"command passes given string unmodifed. Please consider using the hint "
+"table in the case."
+msgstr ""
+
+#: ../../functional_limitations.md:23 e78a48e7582f4ecb9e4a33b9b95cf595
+msgid "Work with `pg_stat_statements`"
+msgstr ""
+
+#: ../../functional_limitations.md:25 028c3c93e75944edb2df54987c87fef6
+msgid ""
+"`pg_stat_statements` generates a query id ignoring comments. As the "
+"result, the identical queries with different hints are summarized as the "
+"same query."
+msgstr ""
+