feat:Add chinese doc

[ZiyiTsang]

Support Multi-languadge
See demo: https://ziyitsang.github.io/AReaL

Auto-remember user's language and replay when browsed again

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not
  work as expected)
• Documentation update
• Code refactoring (no functional changes)
• Performance improvement
• Test coverage improvement

Checklist

• I have read the Contributing Guide
• I have run formatting tools (pre-commit or manual)
• I have run relevant unit tests and they pass
• I have added tests for new functionality
• I have updated documentation if needed
• My branch is up to date with main
• This PR introduces breaking changes (if yes, fill out details below)
• If this PR changes documentation, I have built and previewed it locally with
  jb build docs
• No critical issues raised by AI reviewers (/gemini review)

Breaking Change Details (if applicable):

Additional Context

---

Need help? Check the Contributing Guide or ask in
GitHub Discussions!

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the AReaL project's documentation by introducing full multi-language support. The changes involve a major restructuring of the documentation directory, the addition of Chinese translations for all key guides and references, and the implementation of interactive features for language switching. This initiative aims to make the project's extensive documentation accessible to a wider, global audience, fostering broader adoption and understanding of AReaL's capabilities.

Highlights

• Multi-language Documentation System: Implemented a comprehensive multi-language documentation system for AReaL, supporting both English and Chinese content.
• Documentation Restructuring: Migrated all existing English documentation files into a dedicated 'docs/en/' directory and introduced new Chinese documentation under 'docs/zh/'.
• Interactive Language Toggle: Added client-side JavaScript and CSS to provide a seamless language toggle button in the documentation, allowing users to switch between English and Chinese and remember their preference.
• Automated Documentation Build: Introduced a new shell script ('build_all.sh') to automate the process of building both English and Chinese versions of the documentation using Jupyter Book.
• Enhanced CLI Documentation Generation: Updated the 'generate_cli_docs.py' script to dynamically generate CLI reference documentation in both English and Chinese, adapting to the new multi-language structure.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/README.md
  • Removed the top-level documentation README, as its content has been integrated into the new multi-language structure.
• docs/_config.yml.backup
  • Updated the main Jupyter Book configuration to include assets for the language toggle functionality, then renamed to a backup as new language-specific configs were introduced.
• docs/_static/css/lang-toggle.css
  • Added new CSS styles to visually define the language toggle button, ensuring a consistent look across the documentation.
• docs/_static/js/lang-toggle.js
  • Added JavaScript logic to handle language switching, detect the current language, build target URLs, and store user preferences in local storage.
• docs/build_all.sh
  • Added a new shell script to automate the building process for both English and Chinese documentation, including the creation of a root index page for redirection.
• docs/en/_config.yml
  • Added the Jupyter Book configuration file specifically for the English version of the documentation.
• docs/en/_toc.yml
  • Renamed the main table of contents file to serve as the table of contents for the English documentation, with minor content reformatting.
• docs/en/algorithms/async.md
  • Renamed the asynchronous RL documentation file to its English-specific path and reformatted content for improved readability.
• docs/en/algorithms/grpo_series.md
  • Renamed the GRPO series algorithms documentation file to its English-specific path and reformatted content for improved readability.
• docs/en/algorithms/m2po.md
  • Renamed the M2PO algorithm documentation file to its English-specific path and reformatted content for improved readability.
• docs/en/algorithms/prox_approx.md
  • Renamed the proximal log-probability approximation documentation file to its English-specific path and reformatted content for improved readability.
• docs/en/best_practices/algo_perf.md
  • Renamed the algorithm performance best practices documentation file to its English-specific path and reformatted content for improved readability.
• docs/en/best_practices/debugging.md
  • Renamed the debugging best practices documentation file to its English-specific path.
• docs/en/best_practices/handling_oom.md
  • Renamed the OOM handling best practices documentation file to its English-specific path.
• docs/en/best_practices/perf_profiling.md
  • Renamed the performance profiling best practices documentation file to its English-specific path.
• docs/en/best_practices/workflow.md
  • Renamed the workflow best practices documentation file to its English-specific path.
• docs/en/cli_reference.md
  • Renamed the CLI reference documentation file to its English-specific path.
• docs/en/customization/agent.md
  • Renamed the agent customization documentation file to its English-specific path.
• docs/en/customization/dataset.md
  • Renamed the dataset customization documentation file to its English-specific path.
• docs/en/intro.md
  • Renamed the introduction documentation file to its English-specific path.
• docs/en/reference/agent_workflow.md
  • Renamed the agent workflow reference documentation file to its English-specific path.
• docs/en/reference/ai_assisted_dev.md
  • Renamed the AI-assisted development reference documentation file to its English-specific path.
• docs/en/reference/alloc_mode.md
  • Renamed the allocation mode reference documentation file to its English-specific path.
• docs/en/reference/checkpointing.md
  • Renamed the checkpointing reference documentation file to its English-specific path.
• docs/en/reference/metrics_tracking.md
  • Renamed the metrics tracking reference documentation file to its English-specific path.
• docs/en/reference/rollout_workflow.md
  • Renamed the rollout workflow reference documentation file to its English-specific path.
• docs/en/reference/tree_training.md
  • Renamed the tree training reference documentation file to its English-specific path.
• docs/en/tutorial/agentic_rl.md
  • Renamed the agentic RL tutorial documentation file to its English-specific path.
• docs/en/tutorial/archon.md
  • Renamed the Archon tutorial documentation file to its English-specific path.
• docs/en/tutorial/eval.md
  • Renamed the evaluation tutorial documentation file to its English-specific path.
• docs/en/tutorial/gsm8k_grpo.md
  • Renamed the GSM8K GRPO tutorial documentation file to its English-specific path.
• docs/en/tutorial/installation.md
  • Renamed the installation tutorial documentation file to its English-specific path.
• docs/en/tutorial/installation_npu.md
  • Renamed the NPU installation tutorial documentation file to its English-specific path.
• docs/en/tutorial/megatron.md
  • Renamed the Megatron tutorial documentation file to its English-specific path.
• docs/en/tutorial/quickstart.md
  • Renamed the quickstart tutorial documentation file to its English-specific path.
• docs/en/version_history.md
  • Renamed the version history documentation file to its English-specific path.
• docs/generate_cli_docs.py
  • Modified the CLI documentation generation script to support generating content for both English and Chinese languages.
• docs/zh/_config.yml
  • Added the Jupyter Book configuration file specifically for the Chinese version of the documentation.
• docs/zh/_toc.yml
  • Added the table of contents file specifically for the Chinese documentation.
• docs/zh/algorithms/async.md
  • Added Chinese translation for the asynchronous RL documentation.
• docs/zh/algorithms/grpo_series.md
  • Added Chinese translation for the PPO, GRPO, and related algorithms documentation.
• docs/zh/algorithms/m2po.md
  • Added Chinese translation for the M2PO algorithm documentation.
• docs/zh/algorithms/prox_approx.md
  • Added Chinese translation for the proximal log-probability approximation documentation.
• docs/zh/best_practices/algo_perf.md
  • Added Chinese translation for the algorithm performance best practices documentation.
• docs/zh/best_practices/debugging.md
  • Added Chinese translation for the debugging guide documentation.
• docs/zh/best_practices/handling_oom.md
  • Added Chinese translation for the OOM handling best practices documentation.
• docs/zh/best_practices/perf_profiling.md
  • Added Chinese translation for the performance profiling documentation.
• docs/zh/best_practices/workflow.md
  • Added Chinese translation for the agent workflow best practices documentation.
• docs/zh/customization/agent.md
  • Added Chinese translation for the agent customization documentation.
• docs/zh/customization/dataset.md
  • Added Chinese translation for the dataset customization documentation.
• docs/zh/intro.md
  • Added Chinese translation for the introduction documentation.
• docs/zh/reference/agent_workflow.md
  • Added Chinese translation for the agent workflow reference documentation.
• docs/zh/reference/ai_assisted_dev.md
  • Added Chinese translation for the AI-assisted development reference documentation.
• docs/zh/reference/alloc_mode.md
  • Added Chinese translation for the allocation mode reference documentation.
• docs/zh/reference/checkpointing.md
  • Added Chinese translation for the checkpointing reference documentation.
• docs/zh/reference/metrics_tracking.md
  • Added Chinese translation for the metrics tracking reference documentation.
• docs/zh/reference/rollout_workflow.md
  • Added Chinese translation for the rollout workflow reference documentation.
• docs/zh/reference/tree_training.md
  • Added Chinese translation for the tree training reference documentation.
• docs/zh/tutorial/agentic_rl.md
  • Added Chinese translation for the agentic RL tutorial documentation.
• docs/zh/tutorial/archon.md
  • Added Chinese translation for the Archon engine tutorial documentation.
• docs/zh/tutorial/eval.md
  • Added Chinese translation for the evaluation tutorial documentation.
• docs/zh/tutorial/gsm8k_grpo.md
  • Added Chinese translation for the GSM8K GRPO tutorial documentation.
• docs/zh/tutorial/installation.md
  • Added Chinese translation for the installation tutorial documentation.
• docs/zh/tutorial/installation_npu.md
  • Added Chinese translation for the NPU installation tutorial documentation.
• docs/zh/tutorial/megatron.md
  • Added Chinese translation for the large MoE model fine-tuning guide documentation.
• docs/zh/tutorial/quickstart.md
  • Added Chinese translation for the quickstart tutorial documentation.
• docs/zh/version_history.md
  • Added Chinese translation for the version history documentation.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/deploy-docs.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a major update to the documentation by adding support for Chinese translations. This includes restructuring the docs directory, adding a language toggle button with corresponding CSS and JavaScript, and providing a build script for multi-language documentation. A significant number of English documentation files have been moved, and their Chinese translations have been added. The CLI documentation generator has also been updated to support multiple languages.

The changes are well-structured and the implementation of the new features appears solid. I have a few minor suggestions to improve the robustness and readability of the new JavaScript code for the language toggle.

[garrett4wade]

Code Review: PR #969 — feat: Add Chinese doc

Thanks for the multi-language documentation work! Below are findings from a detailed review, grouped by severity. Issues are numbered for easy reference.

---

🔴 CRITICAL

Issue 1: LaTeX Math Formulas Systematically Corrupted (77+ instances)

Files: docs/en/algorithms/grpo_series.md, m2po.md, prox_approx.md + all docs/zh/algorithms/ counterparts

All $$...$$ and $...$ math blocks have been double-escaped, breaking every formula across algorithm documentation:

Original (correct)	PR version (broken)
\text{GRPO}	\\text{GRPO}
\frac{1}{G}	\\frac{1}{G}
_{i=1}^G	\_{i=1}^G
\left[ ... \right]	\\left\[ ... \\right\]
\mathbb{E}	\\mathbb{E}

Example from grpo_series.md:

# Original (renders correctly):
$$ J_{\text{GRPO}}(\theta) = \mathbb{E}_{\substack{q \sim P(Q)}} \left[ \frac{1}{G} \sum_{i=1}^G ... \right] $$

# PR version (completely broken):
$$ J\_{\\text{GRPO}}(\\theta) = \\mathbb{E}_{\\substack{q \\sim P(Q)}} \\left\[ \\frac{1}{G} \\sum\_{i=1}^G ... \\right\] $$

This is likely caused by mdformat running on LaTeX content. MathJax/KaTeX will receive \\ as line breaks instead of \ as command prefixes.

Fix: Revert all LaTeX to original single-backslash form. Consider excluding math blocks from markdown formatting.

---

🟠 HIGH

Issue 2: Conflicting Dependency Install — pip vs uv

File: .github/workflows/deploy-docs.yml (line ~41)

The workflow installs jupyter-book==1.0.4.post1 via pip, but build_all.sh uses uv run --only-dev jupyter-book build (which resolves from pyproject.toml's dev group jupyter-book<2). The pip-installed version is never used — wastes CI time and creates a silent version mismatch risk.

# Current (redundant):
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install --upgrade jupyter-book==1.0.4.post1

Fix: Replace with uv sync --only-dev or remove entirely (uv run auto-syncs).

Issue 3: _config.yml.backup Committed to Repo

File: docs/_config.yml.backup

The original docs/_config.yml was renamed to .backup instead of deleted. Backup files shouldn't live in version control — the old config is available via git history. This also breaks jupyter-book build docs for local development.

Fix: Delete docs/_config.yml.backup.

Issue 4: Broken Markdown Image Paths

Files: docs/en/algorithms/m2po.md:7, docs/zh/algorithms/m2po.md:7

After the restructure docs/algorithms/ → docs/en/algorithms/, relative paths are one level deeper:

![m2po figure](../figures/m2po.png)
# Resolves to docs/en/figures/m2po.png ❌ (doesn't exist)
# Should be:
![m2po figure](../../figures/m2po.png)
# Resolves to docs/figures/m2po.png ✅

Fix: Change ../figures/ to ../../figures/ in all Markdown image references.

Issue 5: Broken Link to Repository Source File

Files: docs/en/tutorial/eval.md:115, docs/zh/tutorial/eval.md:109

Same nesting-depth issue as Issue 4:

See [`examples/math/gsm8k_eval.py`](../../examples/math/gsm8k_eval.py)
# Resolves to docs/examples/ ❌
# Needs ../../../examples/ ✅

Fix: Change ../../examples/ to ../../../examples/.

Issue 6: path_to_book Incorrect — "Edit on GitHub" Links Will 404

Files: docs/en/_config.yml:16, docs/zh/_config.yml:16

repository:
  path_to_book: docs    # Generates links to docs/<file>

With sources now in docs/en/, the "Edit on GitHub" button links to the wrong path.

Fix: Set path_to_book: docs/en in the en config and path_to_book: docs/zh in the zh config.

---

🟡 MEDIUM

Issue 7: Dark Mode CSS Ignores Jupyter Book's Theme Toggle

File: docs/_static/css/lang-toggle.css:57

The dark mode rule only uses @media (prefers-color-scheme: dark) (OS-level). Jupyter Book's built-in toggle sets <html data-theme="dark">, which isn't targeted. Users who toggle dark mode in-docs but have a light OS will see poorly-styled button.

Fix: Add html[data-theme="dark"] .areal-lang-toggle-btn { ... } rules alongside the media query.

Issue 9: build_all.sh Glob Misses Hidden Files

File: docs/build_all.sh:38

mv "$SCRIPT_DIR/_build/en/_build/html/"* "$SCRIPT_DIR/_build/en/" 2>/dev/null || true
rmdir "$SCRIPT_DIR/_build/en/_build/html" "$SCRIPT_DIR/_build/en/_build" 2>/dev/null || true

Bash * doesn't match dotfiles (.buildinfo, etc.). They're left behind, rmdir fails silently (dir not empty), leaving orphaned nested directories in the artifact.

Fix: Add shopt -s dotglob at the top of the script, and use rm -rf instead of rmdir.

Issue 10: Three Copies of lang-toggle.js/css with Inconsistent Content

Files: docs/_static/js/lang-toggle.js, docs/en/_static/js/lang-toggle.js, docs/zh/_static/js/lang-toggle.js (+ CSS equivalents)

The en/zh copies have different error handling than the root copy (e.g., console.warn(...) vs silent catch), but build_all.sh overwrites them with the root version at build time. The committed en/zh copies are dead code.

Fix: Remove docs/{en,zh}/_static/js/lang-toggle.js and CSS equivalents from version control. Keep only docs/_static/ as the single source of truth.

Issue 11: Non-Standard Jupyter Book Config Keys

Files: docs/en/_config.yml, docs/zh/_config.yml

extra_footerjs, extra_css, build.dir, and build.figureurl are not standard Jupyter Book keys — they are silently ignored. JS/CSS loading may work incidentally via html_extra_path, but this is fragile.

Fix: Use standard Sphinx config for explicit JS/CSS inclusion:

sphinx:
  config:
    html_js_files:
      - js/lang-toggle.js
    html_css_files:
      - css/lang-toggle.css

Remove build.dir and build.figureurl (they're no-ops).

Issue 12: Config Parameter Name Typo in Documentation

File: docs/en/best_practices/algo_perf.md:101

- Ensure `behave_imp_weight_cap` is set (recommended value: 5).

The actual codebase uses behav_imp_weight_cap (confirmed in cli_args.py, actor.py). Users will use a non-existent config key.

Fix: Revert to behav_imp_weight_cap.

---

🟢 LOW

Issue 13: Dead Code in build_all.sh (lines 49-85)

After mv on line 38 moves all contents, lines 49-85 try to copy from the same (now-removed) directory. These if conditions are always false.

Fix: Remove lines 49-85.

Issue 14: Redundant Manual UV Cache Config

File: .github/workflows/deploy-docs.yml:34

astral-sh/setup-uv@v4 supports enable-cache: true natively. The manual actions/cache@v3 step is redundant and doesn't include uv.lock in its key.

Fix: Remove manual cache step; add enable-cache: true to setup-uv.

Issue 15: No Duplicate-Button Prevention in lang-toggle.js

File: docs/_static/js/lang-toggle.js (createButton function)

If the script loads twice, a second button is appended. The id is set but never checked.

Fix: Add if (document.getElementById('areal-lang-toggle')) return; at the start of createButton().

Issue 16: Dead Code in buildTargetUrl()

File: docs/_static/js/lang-toggle.js:54,80

currentLang is assigned but never read. url.pathname is assigned on line 80 then overwritten on line 90.

Fix: Remove the unused variable and the first pathname assignment.

Issue 18: !important on Shared Container Class

File: docs/_static/css/lang-toggle.css:52-54

.header-article-items__end {
    align-items: center !important;
}

This targets the entire header container, not just the toggle button.

Fix: Scope to .header-article-items__end .areal-lang-toggle-btn { align-self: center; }.

---

Summary

Severity	Count	Blocking?
CRITICAL	1 (77+ instances)	✅ Yes
HIGH	5	✅ Yes
MEDIUM	6	Recommended
LOW	4	Nice-to-have

Issue 1 (LaTeX corruption) is a merge blocker — it renders all algorithm documentation math unreadable. Issues 2-6 should also be addressed before merge.

[ZiyiTsang]

Done
@garrett4wade

[ZiyiTsang]

ignore issue 1/2, it is LLM hallucination

[garrett4wade]

This file should be reverted.

[garrett4wade]

should use uv, as mentioned above

[garrett4wade]

The current CI workflow has a pinned jupyter-book version installed via pure pip:

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install --upgrade jupyter-book==1.0.4.post1

However, we should use uv sync --only-dev to install the jupyterbook specified in pyproject.toml. (Or you should change pyproject.toml to pin the version as well.) This is for the integrity of the project. The environment for building docs should be the same in CI and in a locally installed environment.

[ZiyiTsang]

yes make sense, wait..

[ZiyiTsang]

Done, I change in pyproject.toml
Github action works fine

[ZiyiTsang]

@garrett4wade

[garrett4wade]

LGTM