文档¶

新翻译语言¶

我们希望提供尽可能完整的翻译。但是，翻译文件可能有时不会是最新的。您应始终将英文版本视为权威版本。

如果您的语言不在当前语言中，请通过 Github 联系我们，我们会考虑为其创建一个骨架文件夹。以下部分是您应该考虑翻译的第一部分，因为这些文件不会经常更改

• index.rst

• intro.rst

• quickstart.rst

• installation.rst

• /intro 文件夹

• /tutorials-and-examples 文件夹

文档管理员提醒¶

所有语言文件夹的结构应镜像英文文件夹结构。如果英文版本的结构发生变化，我们应该将这些更改应用到其他语言中。

例如，如果在 en/file.rst 中创建了一个新的英文文件，我们应该

• 在所有其他语言中添加文件：fr/file.rst、zh/file.rst、…

• 删除内容，但保留 title、meta 信息以及可能的 toc-tree 元素。以下说明将在没有人翻译该文件时添加

  File Title
  ##########
  
  .. note::
      The documentation is not currently supported in XX language for this
      page.
  
      Please feel free to send us a pull request on
      `Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
      button to directly propose your changes.
  
      You can refer to the English version in the select top menu to have
      information about this page's topic.
  
  // If toc-tree elements are in the English version
  .. toctree::
      :maxdepth: 1
  
      one-toc-file
      other-toc-file
  
  .. meta::
      :title lang=xx: File Title
      :keywords lang=xx: title, description,...
  

翻译技巧¶

• 在您想要翻译内容的语言中浏览和编辑 - 否则您将看不到已经翻译的内容。

• 如果您的选择的语言已经在书籍中存在，请随时直接进入。

• 使用 非正式形式。

• 同时翻译内容和标题。

• 在提交更正之前，请与英文内容进行比较（如果您更正了某些内容，但没有整合“上游”更改，您的提交将不会被接受）。

• 如果您需要编写英文术语，请将其用 <em> 标签括起来。例如，“asdf asdf Controller asdf” 或 “asdf asdf Kontroller (Controller) asfd”。

• 不要提交部分翻译。

• 不要编辑具有未决更改的部分。

• 不要使用 HTML 实体 表示重音字符，书籍使用 UTF-8。

• 不要大幅更改标记（HTML）或添加新内容。

• 如果原始内容缺少某些信息，请先提交对其的编辑。

行长¶

文本行应在 80 列处换行。唯一的例外应该是长 URL 和代码片段。

标题和章节¶

章节标题通过用至少与文本长度相同的标点符号下划线标题来创建。

• # 用于表示页面标题。

• = 用于表示页面中的章节。

• - 用于表示小节。

• ~ 用于表示小小节。

• ^ 用于表示小小小小节。

标题的嵌套深度不应超过 5 层。标题前后应留空行。

段落¶

段落只是文本块，所有行都具有相同的缩进级别。段落之间应留空行。

内联标记¶

• 一个星号：text 表示强调（斜体） 我们将它用于一般突出显示/强调。

  • *text*.

• 两个星号：text 表示强烈强调（粗体） 我们将它用于工作目录、项目符号列表主题、表名，不包括以下词语“table”。

  • **/config/Migrations**, **articles**, 等等。

• 两个反引号：text 表示代码示例 我们将它用于方法选项名称、表列名称、对象名称，不包括以下词语“object”，以及方法/函数名称 - 包含“()”。

  • ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, 等等。

如果星号或反引号出现在运行文本中，可能会与内联标记分隔符混淆，则必须用反斜杠对其进行转义。

内联标记有一些限制

• 它不能嵌套。

• 内容不能以空格开头或结尾：* text* 是错误的。

• 内容必须用非单词字符与周围文本隔开。使用反斜杠转义的空格来解决此问题：onelong\ *bolded*\ word。

列表¶

列表标记与 markdown 非常相似。无序列表用一行开头用单个星号和空格来表示。编号列表可以使用数字或 # 进行自动编号

* This is a bullet
* So is this. But this line
  has two lines.

1. First line
2. Second line

#. Automatic numbering
#. Will save you some time.

还可以通过缩进部分并将它们用空行隔开来创建缩进列表

* First line
* Second line

    * Going deeper
    * Whoah

* Back to the first level.

可以通过执行以下操作来创建定义列表

term
    definition
CakePHP
    An MVC framework for PHP

术语不能超过一行，但定义可以是多行，并且所有行应保持一致的缩进。

链接¶

有几种类型的链接，每种链接都有其自己的用途。

`External Link to php.net <https://php.ac.cn>`_

描述类及其内容¶

CakePHP 文档使用 phpdomain 来提供用于描述 PHP 对象和构造的自定义指令。使用这些指令和角色是提供适当索引和交叉引用功能的必要条件。

描述类和构造¶

每个指令都会填充索引，或者填充命名空间索引。

.. php:global:: name¶

此指令声明一个新的 PHP 全局变量。

.. php:function:: name(signature)¶

定义一个不在类之外的新的全局函数。

.. php:const:: name¶

此指令声明一个新的 PHP 常量，您也可以在类指令内嵌套使用它来创建类常量。

.. php:exception:: name¶

此指令在当前命名空间中声明一个新的异常。签名可以包含构造函数参数。

.. php:class:: name¶

描述一个类。属于该类的类方法、属性和常量应该位于此指令的主体中

.. php:class:: MyClass

    Class description

   .. php:method:: method($argument)

   Method description

属性、类方法和常量不需要嵌套。它们也可以直接跟随类声明

.. php:class:: MyClass

    Text about the class

.. php:method:: methodName()

    Text about the method

另请参阅

php:method、php:attr、php:const

.. php:method:: name(signature)¶

描述一个类方法，包括其参数、返回值和异常

.. php:method:: instanceMethod($one, $two)

    :param string $one: The first parameter.
    :param string $two: The second parameter.
    :returns: An array of stuff.
    :throws: InvalidArgumentException

   This is an instance method.

.. php:staticmethod:: ClassName::methodName(signature)¶

描述一个静态方法，包括其参数、返回值和异常，有关选项，请参见 php:method。

.. php:attr:: name¶

描述类上的属性/属性。

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

源代码¶

文字代码块是通过以 :: 结束段落来创建的。文字块必须缩进，并且与所有段落一样，由单行分隔

This is a paragraph::

    while ($i--) {
        doStuff()
    }

This is regular text again.

文字文本不会被修改或格式化，除非删除一层缩进。

备注和警告¶

通常您想通知读者有关重要提示、特殊备注或潜在风险的信息。Sphinx 中的告诫就是为此目的而设计的。有五种告诫。

• .. tip:: 技巧用于记录或重申有趣或重要的信息。指令内容应以完整的句子编写，并包含所有适当的标点符号。

• .. note:: 备注用于记录特别重要的信息。指令内容应以完整的句子编写，并包含所有适当的标点符号。

• .. warning:: 警告用于记录潜在的障碍或与安全相关的信息。指令内容应以完整的句子编写，并包含所有适当的标点符号。

• .. versionadded:: X.Y.Z “版本添加”告诫用于显示特定于在特定版本添加的新功能的备注，X.Y.Z 是添加该功能的版本。

• .. deprecated:: X.Y.Z 与“版本添加”告诫相反，“已弃用”告诫用于通知已弃用的功能，X.Y.Z 是该功能被弃用的版本。

所有告诫都是一样的

.. note::

    Indented and preceded and followed by a blank line. Just like a
    paragraph.

This text is not part of the note.