DOCSEARCHbyAlgolia
Submit Docs

PHP Documentation Chinese Translation

repository·master·Indexed 41 days ago

https://github.com/php/doc-zh

Official Chinese translation of the PHP documentation maintained in DocBook XML format. This resource provides guidelines for contributors on setting up the translation environment, using the EN-Revision header for synchronization with English sources, XML validation via configure.php, and linguistic best practices for Chinese formatting and HTML rendering.

Tokens
2.2K
Snippets
4
Records
12
Agent score
2%

What's inside PHP

  1. Use the EN-Revision header for translation tracking

    master

    Every translated XML file must include a specific header comment to track synchronization with the English source. This header allows the system to detect if a translation is outdated.

    Replace the first two lines of the original English document with the following format:

    <?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: [commit_hash] Maintainer: [username] Status: [ready|partial] -->

    Header Variables

    VariableDescription
    EN-RevisionThe commit hash of the corresponding English documentation. Crucial for update detection.
    MaintainerYour username (must match the nick in translation.xml, case-sensitive).
    StatusUse ready when finished, or partial if only partially translated.
    CREDITS(Optional) Add <!-- CREDITS: username1, username2 --> to credit contributors who performed major updates.
    <!-- EN-Revision: 68a9c82e06906a5c00e0199307d87dd3739f719b Maintainer: johnsmith Status: ready -->

  2. Synchronize outdated translations with English source

    master

    If the English documentation changes, your Chinese translation becomes outdated. To sync:

    1. Use the doc.php.net tool to identify outdated files.
    2. Check the diff provided by the tool to see what changed in the English source (e.g., parameter type changes).
    3. Apply the corresponding changes to your .xml file in the zh directory.
    4. Update the EN-Revision commit hash in your file header to match the latest English version.
    5. (Optional) Add your name to CREDITS if you performed a significant update.

  3. Translate a new documentation file

    master

    When a function or feature exists in English but not yet in Chinese, follow these steps:

    1. Navigate to the en directory.
    2. Find the commit hash of the English file using git log. For example, to find the hash for in_array():
      git log -n1 --pretty=format:%H -- reference/array/functions/in-array.xml
    3. Use that hash in your new Chinese file's header:
   ```xml
   <?xml version="1.0" encoding="utf-8"?>
   <!-- EN-Revision: [the_hash_you_found] Maintainer: [your_username] Status: ready -->
    git log -n1 --pretty=format:%H -- reference/array/functions/in-array.xml

  4. Best practices for Chinese translation formatting

    master

    To ensure high-quality documentation and proper rendering in HTML, follow these formatting rules:

    Text and Punctuation

    • Line Endings: Use UNIX format (\n), not DOS (\r\n).
    • Indentation: Use spaces, never use tabs (\t).
    • Punctuation: Use full-width Chinese punctuation marks.
    • Spacing: Use spaces between Chinese characters and English words/numbers. Do not put spaces between Chinese characters and Chinese punctuation.
    • Terminology: Do not translate technical terms like TRUE, FALSE, or Boolean.
    • Style: Use formal written Chinese and check for typos.

    Handling Line Breaks in XML

    To prevent unwanted spaces in the rendered HTML (caused by line breaks in the XML), follow these patterns:

    Avoid this (breaks flow):

    <para>
    本节内容适用于 Windows 95/98/Me 以及 Windows NT/2000/XP。
    PHP 不能在 16 位平台运行。
</para>

    Preferred (keep English words/numbers as anchors for breaks): Keep line breaks around English words to maintain XML readability without breaking the HTML visual flow:

    <para>
    本节内容适用于 Windows 95/98/Me 以及
    Windows NT/2000/XP。PHP 不能在 16 位平台例如
    Windows 3.1 下运行。
</para>

    For pure Chinese text: Put the entire content on a single line within the <para> tag.

  5. Set up the PHP documentation translation environment

    master

    To contribute to the PHP Chinese documentation, you need a macOS/Linux environment with php and git installed. Follow these steps to prepare your workspace:

    1. Create a working directory:
    mkdir ~/php-docs
cd ~/php-docs
    1. Clone the necessary repositories into a phpdoc directory:
    mkdir phpdoc
cd phpdoc
git clone git@github.com:php/doc-en.git en
git clone git@github.com:php/doc-zh.git zh
git clone git@github.com:php/doc-base.git

    Note: The documentation files are stored in .xml format using the DocBook standard.

    mkdir ~/php-docs
cd ~/php-docs
mkdir phpdoc
cd phpdoc
git clone git@github.com:php/doc-en.git en
git clone git@github.com:php/doc-zh.git zh
git clone git@github.com:php/doc-base.git

  6. Handle Spacing in Chinese XML for Better HTML Rendering

    master

    When translating XML to Chinese, continuous spaces or newlines between Chinese characters and punctuation can cause unwanted gaps in the rendered HTML.

    The Problem: In English, newlines in XML are treated as single spaces. In Chinese, spaces between characters and punctuation look broken.

    The Solution:

    1. For pure Chinese text: Keep the entire paragraph on a single line in the XML to ensure no extra spaces are injected.
    2. For mixed Chinese/English text: You can use newlines to improve XML readability, but do not place a newline immediately before or after a Chinese punctuation mark. Instead, place newlines around English words, as the space between English and Chinese is expected and visually acceptable.

  7. Quick Start: Translate PHP Documentation Online

    master

    The simplest way to participate in translating the PHP documentation is to use the official online editor provided by the PHP project. This avoids the need for local environment setup, SVN/CVS accounts, or complex XML editing.

    Access the editor at: https://edit.php.net

  8. Set up SVN for Documentation Translation

    master

    PHP documentation has migrated to SVN. To translate via SVN, follow these steps:

    1. Checkout the Chinese Documentation

    svn checkout http://svn.php.net/repository/phpdoc/zh/trunk

    2. Activate your SVN Account

    If you have an existing CVS account, you can sync it to SVN by performing one of the following:

    Your account will be synchronized to SVN within approximately 15 minutes, allowing you to use your existing credentials to commit files.

  9. Translation Best Practices and Rules

    master

    When translating PHP documentation files, adhere to the following technical and stylistic rules:

    Technical Requirements

    • File Format: Use UNIX line endings (\n). Do not use DOS/Windows line endings (\r\n).
    • Indentation: Use spaces instead of <TAB> (tab characters) for indentation.
    • Validation: Before submitting any translated XML file, you must run the following command to check for syntax and spelling errors:
      php configure.php --with-lang=zh

    Linguistic and Stylistic Rules

    • Punctuation: Use Chinese punctuation marks.
    • Spacing:
      • Use spaces between Chinese and English words/numbers.
      • Do not use spaces between Chinese words and Chinese punctuation.
    • Terminology: Do not translate technical keywords such as TRUE, FALSE, or Boolean.
    • Tone: Use formal, written Chinese (书面语) and double-check for typos before submission.
    • Workflow: To prevent duplicate work, add your information to translation.xml and update your progress immediately upon starting a file, rather than waiting until completion.

  10. Validate XML files before submitting

    master

    Before submitting a Pull Request, you must verify that your XML files are syntactically correct and free of spelling errors using the provided configuration script:

    php configure.php --with-lang=zh
    php configure.php --with-lang=zh

  11. Identify Yourself in translation.xml

    master

    To track contributors, add your information to translation.xml using the following format:

    <person name="Name" email="email@example.com" nick="nickname" vcs="yes" svn="yes" />

    Parameter Definitions:

    • name: The name displayed on the documentation homepage.
    • email: Your contact email address.
    • nick: Your nickname. This must match the Maintainer field in the header of the files you translate (case-sensitive).
    • svn: Indicates if you have an SVN account.
    • vcs: Used by revcheck.php for validation.

  12. Manage File Headers and Metadata

    master

    To maintain synchronization with the English source and track versions, replace the first two lines of the original English XML document with the following four lines:

    <?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- $Author$ -->
<!-- EN-Revision: [VERSION_NUMBER] Maintainer: [NICKNAME] Status: [STATUS] -->

    Field Explanations:

    • $Revision$: The Chinese document version number (automatically updated; new files start at 1.1).
    • $Author$: The CVS/SVN account of the last person to check in the file (automatically updated).
    • EN-Revision: The version number of the corresponding English document. Crucial for detecting updates.
    • Maintainer: The maintainer of this Chinese file. Must match your nick in translation.xml (case-sensitive).
    • Status: Set to ready when translation is complete, or partial if in progress.
    • CREDITS: (Optional) Add <!-- CREDITS: nick1,nick2 --> if you have performed major updates or significant translation work on a file maintained by others.