使用SitePoint的RTDSphinx-PHP的快速多语言文档

This post will guide you through getting up and running with RTDSphinx-PHP, a ReadTheDocs-friendly Sphinx based PHP documentation skeleton with sane defaults, pre-installed directives, and modified styles for optimal API and prose documentation rendering in multiple languages. For an unfinished example of the documentation, see here and switch the language in the bottom left flyout panel.

这篇文章将指导您启动并运行RTDSphinx-PHP ，这是一个ReadTheDocs友好的基于SphinxPHP文档框架，具有合理的默认值，预安装的指令以及经过修改的样式，可实现多种语言的最佳API和散文文档呈现。 有关文档的未完成示例，请参见此处，并在左下方弹出面板中切换语言。

If this sounds familiar, it’s because we already went through a manual setup of a similar skeleton in a previous post, but that one had no localization support, too many steps, and wasn’t as reusable as this newly developed one. This guide will not be a “let’s build it from scratch” project, but rather an overview of the features this skeleton project offers out of the box, and an introduction into its usage.

如果听起来很熟悉，那是因为我们在上一篇文章中已经对类似的骨架进行了手动设置，但是没有本地化支持，步骤太多，并且不如此新开发的那样可重用。 本指南将不是一个“让我们从头开始构建”项目，而是该框架项目开箱即用提供的功能概述，以及其用法简介。

This post will be the first in a long line of many SitePoint branded projects meant for wide-spread public consumption, fully open source and highly welcoming of other people’s contributions.

这篇文章将是许多SitePoint品牌项目的长篇文章的第一篇，这些项目旨在广泛的公共消费，完全开源和高度欢迎其他人的贡献。

快速开始 (Quickstart)

For prerequisites, make sure you have Python and pip, the Python package manager, installed.

先决条件，请确保您有Python和pip ，Python的包管理器， 安装 。

First, clone the skeleton into a folder – either a subfolder of your project, like projectRoot/docs or into its own folder – anything goes.

首先，将框架克隆到一个文件夹中-项目的子文件夹(例如projectRoot/docs或它自己的文件夹中-一切正常。

git clone https://github.com/sitepoint/rtdsphinx-php docs

Optionally, create a Python virtual environment.

(可选)创建Python虚拟环境 。

Then, while inside the cloned folder, install prerequisites from the requirements.txt file by running:

然后，在克隆的文件夹中，通过运行以下命令从requirements.txt文件安装必备组件：

pip install -r requirements.txt

This will install all necessary packages.

这将安装所有必需的软件包。

That’s it. To generate files for a new language, run:

而已。 要生成新语言的文件，请运行：

bin/update.sh xx

… where xx is the language code (e.g. “jp” for Japanese). Then, edit files in locale/xx/LC_MESSAGES that end in .po.

…其中xx是语言代码(例如，日语为“ jp”)。 然后，在locale/xx/LC_MESSAGES中编辑以.po结尾的文件。

To compile the HTML from these translations, run:

要从这些翻译中编译HTML，请运行：

bin/build.sh xx yy zz

… where xx, yy and zz are language codes for all the languages you want to build. Inspect your generated HTML by opening _build/html/xx/index.html in a browser.

…其中xx ， yy和zz是要构建的所有语言的语言代码。 通过在浏览器中打开_build/html/xx/index.html来检查生成HTML。

For deploying to ReadTheDocs, see below.

有关部署到ReadTheDocs的信息，请参见下文。

特征 (Features)

The following sections will list the features SitePoint’s RTDSphinx-php project has beyond the default Sphinx installation with the RTD theme.

以下各节将列出SitePoint的RTDSphinx-php项目具有的默认功能(具有RTD主题的Sphinx安装)以外的功能。

本土化 (Localization)

Getting localization to work in Sphinx is almost trivially easy. However, it’s not as simple on ReadTheDocs. That’s why this skeleton comes bundled with a ready-to-go localization setup that’s both prepped for local work with custom deployment, and deployment on ReadTheDocs.

在Sphinx中进行本地化工作几乎非常容易。 但是，在ReadTheDocs上并不是那么简单。 这就是为什么此框架与现成的本地化设置捆绑在一起的原因，该本地化设置既可以通过自定义部署进行本地工作，又可以在ReadTheDocs上进行部署。

In the skeleton, you’ll find a locale folder. This folder contains automatically generated language files for languages of your choice. By default, it contains en and hr. If you look inside the LC_MESSAGES folder of each, you’ll notice several *.po files (and some .mo files). The .mo files are machine readable files generated from *.po files, so you don’t need to touch them. .po files are, in turn, created from template files (*.pot), located in _build/locale.

在框架中，您将找到一个locale文件夹。 该文件夹包含自动为您选择的语言生成的语言文件。 默认情况下，它包含en和hr 。 如果查看每个文件夹的LC_MESSAGES文件夹，您会注意到几个*.po文件(和一些.mo文件)。 .mo文件是从*.po文件生成的机器可读文件，因此您无需触摸它们。 .po文件又由位于_build/locale模板文件( *.pot )创建。

To update / create translations, you only update .po files. For example, if you look at the file locale/hr/LC_MESSAGES/01-example.po at lines 18-20:

要更新/创建翻译，您只需更新.po文件。 例如，如果您在第18-20行查看文件locale/hr/LC_MESSAGES/01-example.po ：

#: ../../01-example.rst:17
msgid "The awesome class does awesome things. Instantiate like so::"
msgstr ""

The first line is a gettext comment, telling gettext where the string with the ID which immediately follows comes from. In our case, it comes from /01-example.rst at line 17. The msgid value is the ID of the string to be translated. The msgstr value is what the ID in the text should be replaced with. If we leave msgstr empty, the ID gets printed instead – this ensures that incomplete translations don’t end up showing blank content, but rather their original, (in this case) English version of the missing strings.

第一行是gettext注释，告诉gettext紧随其后的ID字符串的来源。 在我们的情况下，它来自/01-example.rst在线路17。 msgid值是字符串的ID来进行翻译。 msgstr值是文本中的ID应该替换的值。 如果我们将msgstr留为空白，则会打印ID，以确保不完整的翻译不会最终显示空白内容，而是显示原始的(在这种情况下)缺少字符串的英文版本。

If we update this file with a translation:

如果我们使用翻译更新此文件：

#: ../../01-example.rst:17
msgid "The awesome class does awesome things. Instantiate like so::"
msgstr "Ova super klasa radi super stvari. Instancira se ovako::"

and then run:

然后运行：

bin/build.sh hr

The newly generated HTML should reflect this change:

新生成HTML应该反映出这一变化：

You may be wondering how you can define which strings to extract for translation. The answer is – you don’t. Gettext and Sphinx do this for you. They recognize paragraph breaks and sections and automatically pull out anything they think is translatable. This is good – it means you can focus on just writing the original-language docs, and rely on the software to extract it into language files for you, which you can then give directly to your translators.

您可能想知道如何定义要提取的字符串以进行翻译。 答案是–您不会。 Gettext和Sphinx为您做到这一点。 他们识别段落的中断和节，并自动提取他们认为可翻译的内容。 这很好–这意味着您可以专注于仅编写原始语言文档，然后依靠该软件为您将其提取到语言文件中，然后直接将其提供给翻译人员。

实用脚本 (Utility Scripts)

The skeleton comes with several useful utility scripts, all found in the bin subfolder.

该框架附带了几个有用的实用程序脚本，所有这些实用程序脚本都在bin子文件夹中。

The configure.sh script is used to replace some placeholder values in your project with desired ones in one go: the project name, the author name, and the project slug. The slug is the url-friendly name of the project, and will default to a slugified version of the project name if omitted. For example, “My Project” will be slugified into “my-project”. The configuration script is invoked like so:

configure.sh脚本用于一次性将项目中的某些占位符值替换为所需的占位符值：项目名称，作者名称和项目标记。 slug是项目的url友好名称，如果省略，则默认为项目名称的简化版本。 例如，“我的项目”将被归类为“我的项目”。 如下调用配置脚本：

bin/configure.sh "My superb documentation" "John Doe" my-docs

The update.sh script is used to update *.pot files when changes to the source *.rst files are made. It is also used to generate new *.po files from those *.pot files, whether for the existing languages or newly added ones. It does all of this automatically, and only needs language codes in order to know what to update:

当对源*.rst文件进行更改时， update.sh脚本用于更新*.pot文件。 它也可用于从那些*.pot文件生成新的*.po文件，无论是现有的语言还是新添加的语言。 它会自动完成所有这些操作，并且只需要语言代码即可知道要更新的内容：

bin/update.sh jp

The build.sh script compiles the *.po files into machine code *.mo files, and builds the HTML. The resulting HTML can be inspected by opening _build/html/xx/index.html in a browser, where xx is the language code of your choice. For English, Croatian and Japanese at the same time, it is invoked like so:

build.sh脚本将*.po文件编译为机器代码*.mo文件，并生成HTML。 可以通过在浏览器中打开_build/html/xx/index.html来检查生成HTML，其中xx是您选择的语言代码。 对于英语，克罗地亚语和日语同时使用，其调用方式如下：

bin/build.sh hr en jp

PHPDomain和默认语法重点 (PHPDomain and Default Syntax Highlights)

This skeleton project is tweaked for PHP. As such, it defaults to PHP syntax highlighting and comes with PHPDomain pre-installed.

此框架项目针对PHP进行了调整。 因此，它默认为突出显示PHP语法，并预装了PHPDomain 。

The syntax highlighting defaults make sure no code snippets need to be prefixed with <?php, and no explicit language need be defined in PHP code snippets. See bottom of overview.rst for an example:

语法高亮显示的默认设置可确保无需在代码段前添加<?php前缀，并且无需在PHP代码段中定义任何显式语言。 有关示例，请参见overview.rst的底部：

Some other instructions go here::

    $awesome = new Awesome('param');
    $awesome->doGreatThings();

Apart from syntax highlights built-in and activated by default, this skeleton also uses PHPDomain – a set of directives designed for rendering source code documentation in the spirit of PHPDocumentor or ApiGen and similar tools, only less automatic but much more readable.

除了内置的语法高亮和默认情况下激活的语法外，此骨架还使用PHPDomain –一组旨在根据PHPDocumentor或ApiGen和类似工具的精神呈现源代码文档的指令，自动化程度较低，但可读性更高。

It is recommended you use one *.rst file per class in your project, unless you’re dealing with very small classes under the same namespace or interfaces. Using the directives is straightforward:

建议您在项目中为每个类使用一个*.rst文件，除非您要在相同的名称空间或接口下处理非常小的类。 使用指令很简单：

• define the namespace of the class being described:

  定义所描述类的名称空间：

  .. php:namespace:: Cool\Namespace

  The namespace will prefix all classes below it, until a new namespace is declared.

  在声明新的名称空间之前，名称空间将在其下的所有类之前添加前缀。

• define a class:

  定义一个类：

  .. php:class:: Awesome

  Put a class description above or below this declaration, Sphinx doesn’t care. A good practice is putting the general description above, and putting the constructor description and params below the class declaration. Don’t forget the indent the description that comes below the declaration – this is Python, after all.

  在此声明的上方或下方放置一个类说明，Sphinx不在乎。 一个好的做法是将通用描述放在上面，并将构造函数描述和参数放在类声明的下面。 不要忘记缩进声明下面的描述-毕竟是Python。

• define a method – static with .. php:staticmethod:: someStaticMethod() or dynamic with .. php:method:: someMethod(). Add params and returns values like so (careful of the indent!):

  定义一个方法–使用.. php:staticmethod:: someStaticMethod()或使用.. php:method:: someMethod() 。 添加参数并返回如下值(注意缩进！)：

  .. php:staticmethod:: someStaticMethod($someParam)
  
      This method is static. See the ``.rst`` source file for how this is defined. 
      :param string $someParam: A parameter needed by the method
      :returns: void, or throws an \\InvalidArgumentException if the param is invalid
  
      Usage::
  
          Awesome::someStaticMethod($someParam);

By default, methods and classes will get permalinks auto-generated next to them.

默认情况下，方法和类将在它们旁边自动生成永久链接。

However, these links will not appear in the TOC to the left. If you wish to link to arbitrary locations in the documents (these can be locations just above the methods or classes, so you simulate linking to them), use the project’s hidden role. This custom-defined role attaches a class to section elements generated with the role which makes the section invisible in the content (thus not breaking flow) but appearing in the TOC (thus linking to an arbitrary, invisible part of the documentation). The hidden role is used like this:

但是，这些链接不会出现在左侧的目录中。 如果希望链接到文档中的任意位置(这些位置可以在方法或类的上方，因此可以模拟链接到它们)，请使用项目的hidden角色。 该自定义角色将类附加到使用该角色生成的section元素上，该角色使该section在内容中不可见(因此不会中断流程)，但出现在TOC中(因此链接到文档的任意不可见部分)。 隐藏角色的用法如下：

:hidden:`someStaticMethod`
""""""""""""""""""""""""""

The separator can be anything – it doesn’t have to be quotes (") – but it does need to match the length of the wording above it, and it does need to be unindented fully – so all the way to the left. For an example of use, see the raw version of 01-example.rst.

分隔符可以是任何东西–不必是引号( " )–但是它确实需要与它上面的措辞长度匹配，并且也需要完全不缩进-一直到左边。使用示例，请参阅原始版本01-example.rst 。

This combination of plugins and customizations allows for a beautifully rendered source code documentation, deep linked in the table of contents, and explained in depth with tutorial-like prose, for your readers’ convenience.

插件和自定义项的这种组合允许呈现精美的源代码文档，在目录中进行深层链接，并使用类似于教程的散文进行深入说明，以方便读者。

自定义CSS (Custom CSS)

The skeleton comes with CSS overrides of default styles. If you have custom styles you wish to include, add them to the end of the _static/css/my_theme.css file.

该框架带有默认样式CSS替代。 如果您要包含自定义样式，请将其添加到_static/css/my_theme.css文件的末尾。

The CSS files are configured in such a way that changes to them are visible in both local versions, and when deployed to RTD.

CSS文件的配置方式使得在本地版本中以及在部署到RTD时都可以看到对它们的更改。

In the skeleton’s case, custom styles were added to make PHPDomain’s integration with the ReadTheDocs theme prettier, and to make the PHPDomain’s API method links appear in the table of contents.

在框架的情况下，添加了自定义样式，以使PHPDomain与ReadTheDocs主题更加美观，并使PHPDomain的API方法链接出现在目录中。

在ReadTheDocs上发布 (Publishing on ReadTheDocs)

In the previous post, we hosted on RTD by importing our Github repos and selecting from the list. For a multi-language project based on a single source repo, that won’t work – RTD only allows importing a repo from the Github list once. Instead, we need to select the manual option when adding a project:

在上一篇文章中 ，我们通过导入Github存储库并从列表中进行选择来托管RTD。 对于基于单个源存储库的多语言项目，将无法正常工作– RTD仅允许从Github列表中导入一个存储库一次。 而是在添加项目时需要选择手动选项 ：

Sphinx supports localization out of the box, but RTD doesn’t work that way. On RTD, every translation of a project needs to be a separate project in its own right, and then defined as a translation of another project in the latter’s settings:

Sphinx开箱即用地支持本地化，但是RTD不能那样工作。 在RTD上，每个项目的翻译本身都必须是一个单独的项目，然后在后者的设置中定义为另一个项目的翻译：

Every RTD project gets a language selector in the options. RTD, when building the docs, passes this as a parameter to the Sphinx builder. If a Sphinx project has the locales folders defined and a language argument present, the project will be built with that language, provided the language files exist.

每个RTD项目在选项中都有一个语言选择器。 RTD在构建文档时将其作为参数传递给Sphinx构建器。 如果Sphinx项目已定义了locales文件夹并存在language参数，则只要存在语言文件，就将使用该语言来构建项目。

The procedure is:

程序是：

1. Set up the main English project
   设置主要的英语项目

2. Set up a new manual project of a different name for another language. E.g. if en was rtdsphinx, the hr one could be rtdsphinx-hr

   为另一种语言设置一个不同名称的新手动项目。 例如，如果en是rtdsphinx ，则hr可能是rtdsphinx-hr

3. Go into Advanced Settings of each, and input requirements.txt as the requirements file, and conf.py as the configuration file.

   进入每个的高级设置，输入requirements.txt作为需求文件，并输入conf.py作为配置文件。

4. Make sure both build successfully and can be viewed live.
   确保两者都成功构建并且可以实时查看。

5. Go to the main English project, to the Translations menu, and enter the name of the other project (rtdsphinx-hr). Once added, save the project by going to another options screen and clicking Submit (this is necessary because translation linking doesn’t happen until you hit save).

   转到主要的英语项目，进入“翻译”菜单，然后输入另一个项目的名称( rtdsphinx-hr )。 添加完成后，通过转到另一个选项屏幕并单击“提交”来保存项目(这是必须的，因为在您单击“保存”之前，翻译链接不会发生)。

The language should now be switchable in the bottom menu on the main project:

语言现在应该可以在主项目的底部菜单中切换：

结论 (Conclusion)

SitePoint’s RTDSphinx-PHP project is one of many SitePoint-branded open source efforts that will be popping up in the near and far future. If you’re confused about any aspect of this project, please let us know, will you? And if you’d like to contribute or tell us about an issue, the repo is here.

SitePoint的RTDSphinx-PHP项目是许多SitePoint品牌的开放源代码工作之一，这些工作将在不久的将来出现。 如果您对该项目的任何方面感到困惑，请告诉我们，好吗？ 如果您想为某个问题做出贡献或告诉我们，请访问此处的回购。

By having project docs available in several languages, you make your work automatically available to a much wider audience, bringing together thus far unlinked communities. There’s no reason NOT to do it.

通过以多种语言提供项目文档，您可以自动将您的工作提供给更广泛的受众，从而将迄今为止尚未联系的社区聚集在一起。 没有理由不这样做。

Do you localize your project docs? If so, how? If not, why not?

您是否将项目文档本地化？ 如果是这样，怎么办？ 如果没有，为什么不呢？

翻译自: https://www.sitepoint.com/fast-multi-language-docs-with-sitepoints-rtdsphinx-php/