### Skip Dependency Installation

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Skip dependency installation if not needed to speed up the build process.

```bash
# Skip dependency installation if not needed
cmake --preset zh_CN -DAUTO_DEPEND=OFF
cmake --build out/build/zh_CN --target mdbook_build_docs
```

--------------------------------

### Environment Variables Setup

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Setting locale environment variables and Crowdin integration variables.

```bash
export LANG=en_US.UTF-8
export LANGUAGE=en_US
```

```bash
export CROWDIN_PROJECT_ID=<your-project-id>
export CROWDIN_PERSONAL_TOKEN=<your-api-token>
```

--------------------------------

### Workflow 1: Initial Documentation Build

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Steps for the first-time build of documentation for all languages, including configuration, dependency installation, and string extraction.

```bash
# 1. Configure
cmake --preset all

# 2. Prepare repositories (clone upstream Zed docs)
cmake --build out/build/all --target prepare_repositories

# 3. Install dependencies (Rust, mdBook, etc.)
cmake --build out/build/all --target install_requirements

# This takes time (30+ minutes) as it:
# - Creates Conda environment
# - Installs Rust toolchain
# - Builds docs_preprocessor
# - Compiles Zed package

# 4. Extract translatable strings
cmake --build out/build/all --target mdbook_update_pot

# 5. Create translation files for each language
cmake --build out/build/all --target gettext_update_po

# 6. Build HTML documentation
cmake --build out/build/all --target mdbook_build_docs

# Final output: out/zed-html/
```

--------------------------------

### Build All Languages

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Builds documentation for all configured languages.

```bash
cmake --preset all
cmake --build out/build/all

# Output structure:
# out/zed-html/
# 	├── en_US/
# 	├── zh_CN/
# 	└── zh_TW/
```

--------------------------------

### Rebuild Only Specific Steps

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

These examples show how to skip dependencies and run single targets for rebuilding documentation.

```bash
# Just extract strings (don't depend on install_requirements)
cmake --build out/build/all --target mdbook_update_pot --verbose

# Just build documentation (don't update POT/PO)
cmake --build out/build/all --target mdbook_build_docs --verbose
```

--------------------------------

### Initial Setup Workflow

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Steps for initial project setup, including configuration and requirement installation.

```bash
cmake --preset zh_CN
cmake --build out/build/zh_CN --target prepare_repositories
cmake --build out/build/zh_CN --target install_requirements
```

--------------------------------

### Prerequisites Check

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Commands to check if CMake, Git, and Conda are installed and meet the minimum version requirements.

```bash
cmake --version
# Should output: cmake version 3.25.0 or higher
```

```bash
git --version
# Should output: git version 2.x or higher
```

```bash
conda --version
# Should output: conda X.X.X
```

--------------------------------

### Manual Script Execution

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This shows how to set the environment and run a target script directly.

```bash
# Set environment and run script directly
export LANG=en_US.UTF-8 LANGUAGE=en_US

cmake -P cmake/targets/mdbook_update_pot.cmake \
  -DVERSION=main \
  -DLANGUAGE=all \
  # ... other variables
```

--------------------------------

### Build Single Language (Faster)

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Building a single language is faster than building all languages.

```bash
# Faster: Only Simplified Chinese
cmake --preset zh_CN
cmake --build out/build/zh_CN

# Slower: All languages
cmake --preset all
cmake --build out/build/all
```

--------------------------------

### Force Dependency Reinstallation

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This command recompiles all tools even if they are unchanged.

```bash
cmake --preset all -DMODE_OF_INSTALL=ALWAYS
cmake --build out/build/all --target install_requirements
```

--------------------------------

### Build Documentation

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This command builds the documentation, copying verified translations from v1.0 and merging any additional new strings.

```bash
cmake --build . --target gettext_compendium

# 6. Merge any additional new strings
cmake --build . --target gettext_update_po

# 7. Build v2.0 documentation
cmake --build . --target mdbook_build_docs
```

--------------------------------

### Workflow 4: Prepare New Documentation Version

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Steps to prepare a new version of the documentation, inheriting translations from a previous version.

```bash
# 1. Configure for new version with inheritance
cmake -DVERSION=v2.0 -DVERSION_COMPENDIUM=v1.0 .

# 2. Prepare repositories (pulls v2.0 docs)
cmake --build . --target prepare_repositories

# 3. Install dependencies (if needed)
cmake --build . --target install_requirements

# 4. Extract new strings from v2.0 docs
cmake --build . --target mdbook_update_pot

# 5. Create .po files with inherited translations
```

--------------------------------

### Disable Automatic Dependencies

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This shows how to configure the build with AUTO_DEPEND=OFF and manually run targets in order.

```bash
# Configure with AUTO_DEPEND=OFF
cmake --preset all -DAUTO_DEPEND=OFF

# Now must manually run targets in order
cmake --build out/build/all --target prepare_repositories
cmake --build out/build/all --target install_requirements
cmake --build out/build/all --target mdbook_update_pot
cmake --build out/build/all --target gettext_update_po
cmake --build out/build/all --target mdbook_build_docs
```

--------------------------------

### Workflow 2: Update Translations from Crowdin

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Steps to integrate completed translations from Crowdin back into the documentation build.

```bash
# 1. Ensure configuration is current
cmake --preset all

# 2. Download latest translations from Crowdin
cmake --build out/build/all --target crowdin_download_po

# 3. Rebuild documentation with new translations
cmake --build out/build/all --target mdbook_build_docs

# 4. Check translation statistics
cmake --build out/build/all --target gettext_statistics
cat l10n/main/statistics.txt

# Output: Updated out/zed-html/ with latest translations
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Clean build artifacts between runs to ensure a fresh build.

```bash
# Clean build artifacts between runs
rm -rf out/build/
```

--------------------------------

### Troubleshooting: Crowdin Upload Fails

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This provides solutions for Crowdin upload failures due to missing or invalid credentials.

```bash
# Verify environment variables are set
echo "Project ID: $CROWDIN_PROJECT_ID"
echo "Token: ${CROWDIN_PERSONAL_TOKEN:0:10}..."

# If not set, export them
export CROWDIN_PROJECT_ID=12345
export CROWDIN_PERSONAL_TOKEN=your_token_here

# Retry
cmake --build out/build/all --target crowdin_upload_pot
```

--------------------------------

### Troubleshooting: CMake Configuration Fails

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This provides a solution for CMake configuration failures due to an invalid LANGUAGE value.

```bash
# Check valid values
cat languages.json
# Use one of: en_US, zh_CN, zh_TW, or "all"

cmake --preset zh_CN  # Use valid preset
```

--------------------------------

### Workflow 3: Handle New Documentation Strings

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Process for updating translation files when new strings are added to the upstream documentation.

```bash
# 1. Prepare to pick up changes
cmake --preset all

# 2. Update POT templates with new English strings
cmake --build out/build/all --target mdbook_update_pot

# 3. Merge new strings into .po files for each language
# New strings marked as untranslated
# Existing strings preserved
cmake --build out/build/all --target gettext_update_po

# 4. Upload to Crowdin for translator attention
cmake --build out/build/all --target crowdin_upload_pot

# 5. (Translators work in Crowdin)

# 6. Download completed translations
cmake --build out/build/all --target crowdin_download_po

# 7. Rebuild with new translations
cmake --build out/build/all --target mdbook_build_docs
```

--------------------------------

### Analysis Commands

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

These commands help analyze translation progress and identify specific issues.

```bash
# Count untranslated entries:
msgfmt --statistics l10n/main/locale/zh_CN/LC_MESSAGES/*.po

# Find specific fuzzy entries:
grep -r "#, fuzzy" l10n/main/locale/zh_CN/ | head -5

# Get translation statistics:
cmake --build . --target gettext_statistics
cat l10n/main/statistics.txt
```

--------------------------------

### Configure for Single Language Build

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Configures the build process for a single language (Simplified Chinese) using a CMake preset.

```bash
# Navigate to project root
cd /path/to/zed-docs-l10n

# Configure using preset
cmake --preset zh_CN

# Build (automatically runs all dependencies)
cmake --build out/build/zh_CN

# Output will be in:
# out/zed-html/zh_CN/
```

--------------------------------

### Troubleshooting: Missing Translations

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This provides solutions for missing translations in built documentation, including verifying .po files, generating them, and checking build output.

```bash
# Verify .po files exist
ls -la l10n/main/locale/zh_CN/LC_MESSAGES/

# If not found, generate them
cmake --build out/build/all --target gettext_update_po

# Check for errors in build output
cmake --build out/build/all --target mdbook_build_docs --verbose

# Verify .po file syntax
msgfmt --check l10n/main/locale/zh_CN/LC_MESSAGES/*.po
```

--------------------------------

### Inspect Generated Commands

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This command shows the actual CMake/git/cargo commands being executed.

```bash
cmake --build out/build/all --target mdbook_update_pot --verbose

# Output includes full command lines like:
# [Building on ... ]
# /usr/bin/cmake ... -P /path/to/script.cmake
```

--------------------------------

### Configuration for Fuzzy Matching

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Ensure fuzzy matching is enabled in the book.toml configuration or remove fuzzy flags from .po files.

```toml
# In out/repo/docs/book.toml, ensure:
# [preprocessor.i18n]
# fuzzy = true
```

```bash
# Or remove fuzzy flags from .po files
sed -i 's/#, fuzzy//' l10n/main/locale/zh_CN/LC_MESSAGES/*.po
```

--------------------------------

### Specify Custom Configuration

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Overrides cache variables during CMake configuration for custom builds.

```bash
# Custom tool versions
cmake --preset all \
  -DVERSION_OF_RUST=1.90 \
  -DVERSION_OF_MDBOOK=0.4.39

# Custom directories
cmake --preset en_US \
  -DBASEURL_HREF=https://docs.example.com/en

# Different update mode
cmake --preset zh_CN \
  -DMODE_OF_UPDATE=ALWAYS
```

--------------------------------

### Troubleshooting: Fuzzy Entries Blocking Build

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This provides a solution for fuzzy entries blocking the build by editing the mdBook config to allow fuzzy translations.

```bash
# Edit book.toml to allow fuzzy translations
```

--------------------------------

### Cache Conda Environment

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Cache the Conda environment to speed up subsequent runs. The first run installs everything and is slow, while subsequent runs can skip this step.

```bash
# First run: 30+ minutes
cmake --preset all
cmake --build out/build/all --target install_requirements

# Subsequent runs: Skip install_requirements
cmake --preset all -DAUTO_DEPEND=OFF
cmake --build out/build/all --target mdbook_build_docs
```

--------------------------------

### Troubleshooting: Conda Environment Creation Fails

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This provides solutions for Conda environment creation failures, including retrying, forcing reinstallation, and checking disk space.

```bash
# Try again
cmake --build out/build/all --target install_requirements

# Or force reinstallation
cmake --preset all -DMODE_OF_INSTALL=ALWAYS
cmake --build out/build/all --target install_requirements

# Check disk space
df -h
# Need at least 10GB free for build artifacts
```

--------------------------------

### Parallel Compilation

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Utilize multiple CPU cores for parallel compilation to speed up the build process.

```bash
# Build with 4 parallel jobs
cmake --build out/build/all -j 4
```

--------------------------------

### Environment Setup

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/INDEX.md

Required locale setup and optional Crowdin integration environment variables.

```bash
# Locale setup (required)
export LANG=en_US.UTF-8
export LANGUAGE=en_US

# Crowdin integration (optional, for upload/download)
export CROWDIN_PROJECT_ID=<numeric-id>
export CROWDIN_PERSONAL_TOKEN=<api-token>
```

--------------------------------

### Incremental Updates

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

Perform incremental updates by only rebuilding when source changes. This involves downloading PO files and rebuilding the docs, which takes significantly less time than a full build.

```bash
# First build takes 30+ minutes
cmake --build out/build/all

# Subsequent builds without source changes:
# Just update translations and rebuild docs
cmake --build out/build/all --target crowdin_download_po
cmake --build out/build/all --target mdbook_build_docs
# Takes ~10-15 minutes
```

--------------------------------

### Translator Quality Assurance Workflow

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/quickstart-and-examples.md

This workflow outlines the steps for a translator to review translation progress and identify issues.

```bash
# 1. Configure
cmake --preset all

# 2. Generate statistics
cmake --build out/build/all --target gettext_statistics

# 3. View results
cat l10n/main/statistics.txt

# Output example:
# Language: zh_CN
#   Total entries:    250
#   Translated:       180 (72%)
#   Fuzzy:            15 (6%)
#   Untranslated:     55 (22%)

# 4. Investigate fuzzy entries
find l10n/main/locale/zh_CN -name "*.po" -exec grep -l "#, fuzzy" {} \;

# 5. Identify untranslated strings
find l10n/main/locale/zh_CN -name "*.po" -exec grep -B2 'msgstr ""' {} \;

# 6. Work with translators to address gaps
# - Request review of fuzzy entries
# - Provide context for untranslated strings

# 7. Rebuild to verify improvements
cmake --build out/build/all --target mdbook_build_docs
```

--------------------------------

### JavaScript Configuration Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of the ltd-config.js file.

```javascript
"use strict";

var CONFIG_OPTIONS = {
  CONFIG_LANGUAGES: [
    ["en-us",   "English"],
    ["zh-cn",   "简体中文"],
    ["zh-tw",   "繁體中文"],
  ],
  CONFIG_VERSIONS: [
    ["main",    "Development"],
  ],
  CONFIG_PROJECTS: [
    ["Index",   "https://projects.localizethedocs.org"],
    ["Crowdin", "https://localizethedocs.crowdin.com/zed-docs-l10n"],
    ["GitHub",  "https://github.com/localizethedocs/zed-docs-l10n"],
    ["AtomGit", "https://atomgit.com/localizethedocs/zed-docs-l10n"],
    ["GitFlic", "https://gitflic.ru/project/localizethedocs/zed-docs-l10n"],
  ]
};
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/INDEX.md

Example of JSON configuration shown with highlighting.

```json
// JSON configuration shown with json highlighting
{ "key": "value" }
```

--------------------------------

### Project Setup and Build

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/README.md

Commands to clone the repository, set language and version, and build the project using CMake.

```bash
git clone --recurse-submodule https://github.com/localizethedocs/zed-docs-l10n.git
cd zed-docs-l10n
cmake --preset ${LANGUAGE} -DVERSION=${VERSION}
cmake --build out/build/${LANGUAGE}
```

--------------------------------

### versions.json Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/configuration.md

Defines available documentation versions and their configuration.

```json
{
  "dev" : [
    {
      "VERSION" : "main",
      "VERSION_COMPENDIUM" : ""
    }
  ]
}
```

--------------------------------

### Bash Command Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/INDEX.md

Example of a bash command shown in monospace.

```bash
# Bash commands shown in monospace
cmake --preset all
```

--------------------------------

### Example POT File Output

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/translation-workflow.md

Example output content for a POT file.

```pot
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

```

--------------------------------

### versions.json Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

An example of the versions.json file, illustrating configurations for 'dev' and 'stable' channels, including version identifiers and translation inheritance.

```json
{
  "dev" : [
    {
      "VERSION" : "main",
      "VERSION_COMPENDIUM" : ""
    }
  ],
  "stable" : [
    {
      "VERSION" : "v1.0",
      "VERSION_COMPENDIUM" : "main"
    },
    {
      "VERSION" : "v0.9",
      "VERSION_COMPENDIUM" : ""
    }
  ]
}
```

--------------------------------

### Handlebars Template Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of a custom HTML head template using Handlebars.

```handlebars
<!-- Language Selector -->
<script>
  var CONFIG_OPTIONS = {
    CONFIG_LANGUAGES: [
      ["en-us", "English"],
      ["zh-cn", "简体中文"]
    ]
  };
</script>
{{#if is_root}}
  <link rel="canonical" href="{{ baseurl }}/index.html">
{{else}}
  <link rel="canonical" href="{{ baseurl }}/{{ page.path }}">
{{/if}}
```

--------------------------------

### Environment Setup - General

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Required environment variables for any build process.

```bash
export LANG=en_US.UTF-8
export LANGUAGE=en_US
```

--------------------------------

### crowdin.yml Complete Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

A complete example of the crowdin.yml configuration file, demonstrating settings for project ID, API token, base path, hierarchy preservation, and file mappings.

```yaml
#
# Your Crowdin credentials.
#
project_id_env : CROWDIN_PROJECT_ID
api_token_env : CROWDIN_PERSONAL_TOKEN
base_url_env : CROWDIN_BASE_URL

#
# Choose file structure in Crowdin.
#
preserve_hierarchy : true

#
# Use YAML anchor to implement the global languages mapping.
#
languages_mapping: &languages_mapping
  locale:
    zh-CN:  zh_CN
    zh-TW:  zh_TW

#
# Files configuration.
#
files:
  - source: /README.md
    translation: /README.%locale%.md
    languages_mapping: *languages_mapping

```

--------------------------------

### CMake Code Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/INDEX.md

Example of CMake code shown with syntax highlighting.

```cmake
# CMake code shown with cmake syntax highlighting
message(STATUS "Status message")
```

--------------------------------

### references.json Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

An example of the references.json file, showing the tracking of git references for 'en_US' and 'zh_CN' languages.

```json
{
  "en_US" : {
    "pot" : {
      "latest" : "abc123def456",
      "current" : "abc123def456",
      "object" : "commit"
    }
  },
  "zh_CN" : {
    "pot" : {
      "latest" : "abc123def456",
      "current" : "abc123def456",
      "object" : "commit"
    }
  }
}
```

--------------------------------

### PO File Comments Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

An example demonstrating various comment types in a PO file.

```PO
#. Developer note
#: source.md:10
#, fuzzy, c-format
#| msgid "old English text"
msgid "new English text"
msgstr "翻译"
```

--------------------------------

### Build Presets - All Languages

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/language-and-version-system.md

Example of a CMake preset to build all languages for the current version.

```json
{
  "name": "all",
  "cacheVariables": { "LANGUAGE": "all" }
}
```

--------------------------------

### Install Requirements Target

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/CMakeLists.txt

Custom target to install requirements using CMake script mode.

```cmake
add_custom_target(install_requirements
    COMMAND ${CMAKE_COMMAND} -E env ${SCRIPT_MODE_ENV}
            ${CMAKE_COMMAND} ${SCRIPT_MODE_CACHE}
            -P ${PROJ_CMAKE_TARGETS_DIR}/install_requirements.cmake
    VERBATIM)
```

--------------------------------

### Plural Forms Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Examples of Plural-Forms directives for Chinese and French.

```PO
Plural-Forms: nplurals=1; plural=0;
```

```PO
Plural-Forms: nplurals=2; plural=(n > 1);
```

--------------------------------

### languages.json Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/configuration.md

Defines language mappings and identifiers for documentation builds.

```json
{
  "en_US" : {
    "langtag" : "en-us",
    "crowdin" : "en",
    "readthedocs" : "en"
  },
  "zh_CN" : {
    "langtag" : "zh-cn",
    "crowdin" : "zh-CN",
    "readthedocs" : "zh_CN"
  },
  "zh_TW" : {
    "langtag" : "zh-tw",
    "crowdin" : "zh-TW",
    "readthedocs" : "zh_TW"
  }
}
```

--------------------------------

### POT File Line Wrapping Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example demonstrating how long text is split into multiple lines within a POT file to adhere to character limits.

```pot
msgid ""
"Long text that spans "
"multiple lines to stay "
"within character limit"
msgstr ""
```

--------------------------------

### HTML Template Substitution Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of substitution patterns in an HTML template.

```html
<script>
  const BASE_URL = "@BASEURL_HREF@";
  const VERSION = "@VERSION@";
  const LANGUAGE = "@LANGUAGE@";
</script>
```

--------------------------------

### POT File Structure Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/translation-workflow.md

Example structure of a POT file, showing msgid and empty msgstr.

```pot
#: src/getting-started.md:5
msgid "Welcome to Zed"
msgstr ""

#: src/getting-started.md:12
msgid "Installation Instructions"
msgstr ""
```

--------------------------------

### PO File Plural Entry Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

An example of a plural entry in a PO file.

```PO
#: src/guide.md:100
msgid "%d file"
msgid_plural "%d files"
msgstr[0] "%d 个文件"
```

--------------------------------

### POT File Structure Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example structure of a GNU gettext Portable Object Template (.pot) file, showing header and entry formats.

```pot
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-01-15 10:30:00 +0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: src/getting-started.md:42
msgid "Installation"
msgstr ""

#: src/getting-started.md:55
msgid "Quick Start"
msgstr ""
```

--------------------------------

### CMake Presets Usage

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-structure.md

Example commands for configuring and building documentation using CMake presets.

```bash
cmake --preset zh_CN            # Configure for Simplified Chinese
cmake --build out/build/zh_CN   # Build
```

--------------------------------

### PO File Structure Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/translation-workflow.md

Example structure of a PO file, including translations and fuzzy markers.

```po
msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Language: zh-CN\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: src/getting-started.md:5
msgid "Welcome to Zed"
msgstr "欢迎来到 Zed"

#: src/getting-started.md:12
#, fuzzy
msgid "Installation Instructions"
msgstr "安装说明"
```

--------------------------------

### Version Resolution Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-structure.md

Sets dependency versions based on the current VERSION, with an example for the 'main' branch.

```cmake
if (VERSION MATCHES "^(main)$")
    set(VERSION_OF_RUST                 "1.92")
    set(VERSION_OF_DASEL                "2")
    set(VERSION_OF_MDBOOK               "0.4.40")
    set(VERSION_OF_MDBOOK_I18N_HELPERS  "^0.3")
endif()
```

--------------------------------

### YAML File Mapping Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of a file mapping configuration in YAML, including source, translation pattern, and optional language mappings.

```yaml
files:
  - source: /README.md
    translation: /README.%locale%.md
    languages_mapping: *languages_mapping
```

--------------------------------

### PO File Plural Form Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of the Plural-Forms header in a PO file, showing the formula for determining plural forms.

```po
Plural-Forms: nplurals=1; plural=0;
```

--------------------------------

### Environment Setup - Crowdin

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Required environment variables for Crowdin-related build targets.

```bash
export CROWDIN_PROJECT_ID=<project-id>
export CROWDIN_PERSONAL_TOKEN=<api-token>
```

--------------------------------

### PO File Structure Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example structure of a GNU gettext Portable Object (.po) file, including header and translated entries.

```po
# Translation of Zed Documentation to Chinese (Simplified)
# Copyright (C) 2024 Zed Industries
# This file is distributed under the same license as the Zed package.
# Translator Name <email@example.com>, 2024.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Zed Documentation 1.0\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-01-15 10:30:00 +0000\n"
"PO-Revision-Date: 2024-01-15 14:20:00 +0800\n"
"Last-Translator: Translator Name <email@example.com>\n"
"Language-Team: Chinese (Simplified) <team@example.com>\n"
"Language: zh-CN\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: src/getting-started.md:42
msgid "Installation"
msgstr "安装"

#: src/getting-started.md:55
#, fuzzy
msgid "Quick Start Guide"
msgstr "快速启动指南"
```

--------------------------------

### Information Logging Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-structure.md

Prints all relevant variables to the CMake output for debugging purposes.

```cmake
message(STATUS "LANGUAGE                        = ${LANGUAGE}")
message(STATUS "VERSION                         = ${VERSION}")
message(STATUS "Git_EXECUTABLE                  = ${Git_EXECUTABLE}")
```

--------------------------------

### Build Presets - Specific Language

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/language-and-version-system.md

Example of a CMake preset to build a specific language (Simplified Chinese) for the current version.

```bash
cmake --preset zh_CN
cmake --build out/build/zh_CN
```

--------------------------------

### Manual Target Execution

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Example of running a specific build target without executing its dependencies.

```bash
# Skip all dependencies, run only this target
cmake --build <build-dir> --target <target-name> --verbose
```

--------------------------------

### Multiple Versions Scenario Setup

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/language-and-version-system.md

Configuration for supporting multiple documentation versions (e.g., main and v1.0) using versions.json.

```json
{
  "dev" : [
    {
      "VERSION" : "main",
      "VERSION_COMPENDIUM" : ""
    }
  ],
  "stable" : [
    {
      "VERSION" : "v1.0",
      "VERSION_COMPENDIUM" : "main"
    }
  ]
}
```

--------------------------------

### Fundamental Target Definition

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-structure.md

Example of a CMake custom target definition for preparing repositories, including environment variable setup and script invocation.

```cmake
add_custom_target(prepare_repositories
    COMMAND ${CMAKE_COMMAND} -E env ${SCRIPT_MODE_ENV}
            ${CMAKE_COMMAND} ${SCRIPT_MODE_CACHE}
            -P ${PROJ_CMAKE_TARGETS_DIR}/prepare_repositories.cmake
    VERBATIM)
```

--------------------------------

### Build Documentation for All Languages

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/configuration.md

Command to configure and build documentation for all specified languages using CMake presets.

```bash
cmake --preset all
cmake --build out/build/all --target mdbook_build_docs

```

--------------------------------

### Build Documentation for English

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/configuration.md

Command to configure and build documentation specifically for English using CMake presets.

```bash
cmake --preset en_US
cmake --build out/build/en_US --target mdbook_build_docs

```

--------------------------------

### Statistics.txt Example Content

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example content of the statistics.txt file.

```text
Translation Statistics for main

Language: en_US
  Total entries:    250
  Translated:       250 (100.0%)
  Fuzzy:            0
  Untranslated:     0

Language: zh_CN
  Total entries:    250
  Translated:       180 (72.0%)
  Fuzzy:            15 (6.0%)
  Untranslated:     55 (22.0%)

Language: zh_TW
  Total entries:    250
  Translated:       165 (66.0%)
  Fuzzy:            20 (8.0%)
  Untranslated:     65 (26.0%)
```

--------------------------------

### Build Documentation for Simplified Chinese

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/configuration.md

Command to configure and build documentation specifically for Simplified Chinese using CMake presets.

```bash
cmake --preset zh_CN
cmake --build out/build/zh_CN --target mdbook_build_docs

```

--------------------------------

### Fuzzy Entry Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/translation-workflow.md

An example of a .po file entry marked as fuzzy.

```po
#: src/guide.md:10
#, fuzzy
msgid "Getting Started Guide"
msgstr "入门指南"
```

--------------------------------

### Preview Translations Locally

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/README.md

Commands to preview translations locally.

```bash
make serve-docs
```

--------------------------------

### switch_to_git_reference_on_branch() Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-utility-functions.md

Example usage of the switch_to_git_reference_on_branch function to check out a specific git reference on a local branch.

```cmake
switch_to_git_reference_on_branch(
    IN_LOCAL_PATH   "${PROJ_OUT_REPO_DIR}"
    IN_REFERENCE    "abc123def456"
    IN_BRANCH       "current")
```

--------------------------------

### Status Messages Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-utility-functions.md

Example of using message(STATUS) in CMake for general progress reporting during build or processing.

```cmake
message(STATUS "Processing ${LANGUAGE}...")
```

--------------------------------

### Building Multiple Versions

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/language-and-version-system.md

Commands to build a specific version (v1.0) for all languages with translation inheritance from the main version.

```bash
cmake -DVERSION=v1.0 .
cmake --build . --target gettext_compendium
cmake --build . --target mdbook_build_docs
```

--------------------------------

### get_members_of_json_object() Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-utility-functions.md

Example of using get_members_of_json_object to extract top-level keys from a JSON object string into a CMake list.

```cmake
file(READ "${LANGUAGES_JSON_PATH}" LANGUAGES_JSON_CNT)
get_members_of_json_object(
    IN_JSON_OBJECT      "${LANGUAGES_JSON_CNT}"
    OUT_MEMBER_NAMES    LANGUAGE_LIST)

# Result: LANGUAGE_LIST = [en_US, zh_CN, zh_TW]
```

--------------------------------

### References JSON Initialization

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/CMakeLists.txt

Initializes the references JSON file with language and version information.

```cmake
# Initialize ${REFERENCES_JSON_PATH}.
#]============================================================]

init_references_json_file(
    IN_FILEPATH         "${REFERENCES_JSON_PATH}"
    IN_VERSION_TYPE     "${VERSION_TYPE}"
    IN_VERSION          "${VERSION}"
    IN_INIT_MODE        "language"
    IN_INIT_LIST        "${LANGUAGE_LIST}")
```

--------------------------------

### PO File Plural Form Example (English)

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/file-formats.md

Example of the Plural-Forms header for English, indicating two plural forms (singular and plural).

```po
# English: 2 forms (singular/plural)
Plural-Forms: nplurals=2; plural=(n != 1);
```

--------------------------------

### Output Structure

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/language-and-version-system.md

Illustrates the directory structure for generated HTML documentation, organized by language.

```tree
out/zed-html/
├── en_US/
│   ├── index.html           # English documentation
│   ├── guide.html
│   └── ...
├── zh_CN/
│   ├── index.html           # Simplified Chinese
│   ├── guide.html
│   └── ...
└── zh_TW/
    ├── index.html           # Traditional Chinese
    ├── guide.html
    └── ...
```

--------------------------------

### New Documentation Version Workflow

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Workflow for creating a new documentation version, including setting version variables and building documentation.

```bash
cmake --preset all -D VERSION=next -D VERSION_COMPENDIUM=main
cmake --build out/build/all --target prepare_repositories
cmake --build out/build/all --target install_requirements
cmake --build out/build/all --target gettext_compendium
cmake --build out/build/all --target mdbook_build_docs
```

--------------------------------

### get_reference_of_latest_from_repo_and_current_from_json() Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-utility-functions.md

Example usage of get_reference_of_latest_from_repo_and_current_from_json to determine the latest and current git references, often used for checking update status.

```cmake
get_reference_of_latest_from_repo_and_current_from_json(
    IN_LOCAL_PATH               "${PROJ_OUT_REPO_DIR}"
    IN_JSON_CNT                 "${REFERENCES_JSON_CNT}"
    IN_VERSION_TYPE             "branch"
    IN_BRANCH_NAME              "main"
    IN_TAG_PATTERN              "v*"
    IN_TAG_SUFFIX               ".pot"
    IN_DOT_NOTATION             ".pot"
    OUT_LATEST_OBJECT           LATEST_POT_OBJECT
    OUT_LATEST_REFERENCE        LATEST_POT_REFERENCE
    OUT_CURRENT_OBJECT          CURRENT_POT_OBJECT
    OUT_CURRENT_REFERENCE       CURRENT_POT_REFERENCE)

# Now use variables:
# LATEST_POT_REFERENCE - Latest commit on main branch
# CURRENT_POT_REFERENCE - Previously recorded reference
```

--------------------------------

### Warnings Example

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/cmake-utility-functions.md

Example of using message(WARNING) in CMake to notify the user of a non-critical issue, such as a variable not being defined and a default value being used.

```cmake
if (NOT DEFINED LANGUAGE)
    message(WARNING "LANGUAGE not set, defaulting to 'all'")
    set(LANGUAGE "all")
endif()
```

--------------------------------

### Default Build Invocation

Source: https://github.com/localizethedocs/zed-docs-l10n/blob/main/_autodocs/build-targets.md

Default command to build final HTML documentation in all configured languages.

```bash
cmake --build <build-dir>
```