Comprehensive proofreading and update of the Chinese part of Defold manuals and tutorials. (#565)

* 翻译校对

* 修正

* 完成翻译

* 添加工具说明

* 修正脚本更加通用

* 修正确编码

Author: VectorWorkshopBaoErJie

scripts/README.md

@@ -1,10 +1,10 @@
 # Documentation Consistency Checker
 
-A Python script designed to check consistency between English and Chinese documentation files in the Defold project. This tool compares file structures and Markdown syntax trees to ensure translations maintain the same structure and formatting.
+A Python script designed to check consistency between documentation files in different languages for the Defold project. This tool compares file structures and Markdown syntax trees to ensure translations maintain the same structure and formatting.
 
 ## Features
 
-- **File Structure Comparison**: Compares the directory structure between English and Chinese documentation
+- **File Structure Comparison**: Compares the directory structure between source and target documentation directories
 - **Markdown Syntax Tree Analysis**: Analyzes and compares Markdown syntax elements including:
   - Headers (h1, h2, h3, etc.)
   - Code blocks
@@ -34,52 +34,49 @@ A Python script designed to check consistency between English and Chinese docume
 
 ### Basic Usage
 
-To run a full comparison between English and Chinese documentation:
+To run a full comparison between source and target documentation directories:
 
 ```bash
-python scripts/docs_consistency_checker.py
+python docs_consistency_checker.py --source-dir ./docs/en --target-dir ./docs/zh
 ```
 
-This will:
-- Use default paths: `docs/en` for English documentation and `docs/zh` for Chinese documentation
-- Generate an output file named `docs_structure_comparison.xlsx`
-
 ### Advanced Usage
 
 #### Specify Custom Directories
 
 ```bash
-python scripts/docs_consistency_checker.py --en-dir /path/to/english/docs --zh-dir /path/to/chinese/docs
+python docs_consistency_checker.py --source-dir /path/to/source/docs --target-dir /path/to/target/docs
 ```
 
 #### Check a Specific File
 
 ```bash
-python scripts/docs_consistency_checker.py --file manuals/game-project/game-project.md
+python docs_consistency_checker.py --source-dir ./docs/en --target-dir ./docs/zh --file manuals/game-project/game-project.md
 ```
 
 #### Check Specific File Pairs
 
 ```bash
-python scripts/docs_consistency_checker.py --en-file /path/to/english/file.md --zh-file /path/to/chinese/file.md
+python docs_consistency_checker.py --source-file /path/to/source/file.md --target-file /path/to/target/file.md
 ```
 
 #### Specify Output File
 
 ```bash
-python scripts/docs_consistency_checker.py --output custom_comparison.xlsx
+python docs_consistency_checker.py --source-dir ./docs/en --target-dir ./docs/zh --output custom_comparison.xlsx
 ```
 
 ### Command Line Arguments
 
 | Argument | Description |
 |----------|-------------|
 | `--file` | Specify a particular file to check (relative to docs directory) |
-| `--en-dir` | Path to English documentation directory |
-| `--zh-dir` | Path to Chinese documentation directory |
+| `--source-dir` | Path to source documentation directory |
+| `--target-dir` | Path to target documentation directory |
 | `--output` | Path for the output Excel file |
-| `--en-file` | Path to a specific English file |
-| `--zh-file` | Path to a specific Chinese file |
+| `--source-file` | Path to a specific source file |
+| `--target-file` | Path to a specific target file |
+| `--help` | Show help message and exit |
 
 ## Output
 
@@ -88,21 +85,21 @@ The script generates an Excel file with the following columns:
 1. **File Path**: Relative path of the file
 2. **File Extension**: File extension type
 3. **Top Directory**: Top-level directory containing the file
-4. **English Version Exists**: Whether the file exists in English documentation
-5. **Chinese Version Exists**: Whether the file exists in Chinese documentation
+4. **Source Version Exists**: Whether the file exists in source documentation
+5. **Target Version Exists**: Whether the file exists in target documentation
 6. **Status**: 
    - "Consistent" - File exists in both versions
-   - "English Only" - File exists only in English version
-   - "Chinese Only" - File exists only in Chinese version
+   - "Source Only" - File exists only in source version
+   - "Target Only" - File exists only in target version
    - "Does Not Exist" - File doesn't exist in either version
-7. **English File Size (KB)**: Size of the English file
-8. **Chinese File Size (KB)**: Size of the Chinese file
+7. **Source File Size (KB)**: Size of the source file
+8. **Target File Size (KB)**: Size of the target file
 9. **Markdown Syntax Consistency**: Results of Markdown syntax comparison
 10. **Formula**: Recommended actions for ensuring translation consistency
 
 ## How It Works
 
-1. **File Collection**: The script recursively collects all files from both English and Chinese documentation directories.
+1. **File Collection**: The script recursively collects all files from both source and target documentation directories.
 2. **File Comparison**: It compares the file structures between the two directories.
 3. **Markdown Analysis**: For Markdown files that exist in both versions, the script:
    - Parses the Markdown content to build syntax trees
@@ -127,3 +124,23 @@ The script is organized into several modules:
 - `modules/file_handler.py`: File operations and utilities
 - `modules/markdown_handler.py`: Markdown parsing and comparison
 - `modules/excel_handler.py`: Excel report generation
+
+### Compare entire documentation directories
+```bash
+python docs_consistency_checker.py --source-dir ../docs/en --target-dir ../docs/zh
+```
+
+### Compare specific file
+```bash
+python docs_consistency_checker.py --source-dir ../docs/en --target-dir ../docs/zh --file manuals/introduction.md
+```
+
+### Compare direct file paths
+```bash
+python docs_consistency_checker.py --source-file ../docs/en/manuals/introduction.md --target-file ../docs/zh/manuals/introduction.md
+```
+
+### Get help
+```bash
+python docs_consistency_checker.py --help
+```

scripts/docs_consistency_checker.py

@@ -31,16 +31,6 @@ def run_docs_consistency_check(source_dir=None, target_dir=None, output_file=Non
     # Set console encoding to resolve character display issues
     setup_console_encoding()
 
-    # Set default directories
-    if source_dir is None:
-        source_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "source")
-    
-    if target_dir is None:
-        target_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "target")
-    
-    if output_file is None:
-        output_file = "docs_structure_comparison.xlsx"
-    
     # If specific source and target file paths are specified, use these paths
     if source_file and target_file:
         print(f"Checking files: Source version {source_file}, Target version {target_file}")
@@ -127,8 +117,41 @@ def run_docs_consistency_check(source_dir=None, target_dir=None, output_file=Non
                     print(f"{i}. {issue}")
         else:
             print("No inconsistency issues found, document structure is consistent")
+        return
+    
+    # Check if source and target directories are provided for directory-based operations
+    if source_dir is None and target_dir is None:
+        # Try to use current working directory as a fallback
+        cwd = os.getcwd()
+        if os.path.exists(os.path.join(cwd, "docs")):
+            source_dir = os.path.join(cwd, "docs", "source")
+            target_dir = os.path.join(cwd, "docs", "target")
+            print(f"Using default directories based on current working directory:")
+            print(f"  Source directory: {source_dir}")
+            print(f"  Target directory: {target_dir}")
+        else:
+            print("Error: Source and target directories must be specified.")
+            print("Usage examples:")
+            print("  python docs_consistency_checker.py --source-dir ./docs/en --target-dir ./docs/zh")
+            print("  python docs_consistency_checker.py --source-file ./docs/en/manuals/introduction.md --target-file ./docs/zh/manuals/introduction.md")
+            print("  python docs_consistency_checker.py --source-dir ./docs/en --target-dir ./docs/zh --file manuals/introduction.md")
+            return
+    
+    # Check if source directory exists
+    if source_dir and not os.path.exists(source_dir):
+        print(f"Error: Source directory does not exist: {source_dir}")
+        return
+    
+    # Check if target directory exists
+    if target_dir and not os.path.exists(target_dir):
+        print(f"Error: Target directory does not exist: {target_dir}")
+        return
+    
+    if output_file is None:
+        output_file = "docs_structure_comparison.xlsx"
+    
     # If a specific file is specified, only check that file
-    elif specific_file:
+    if specific_file:
         print(f"Checking specific file: {specific_file}")
 
         # Build complete file paths

scripts/modules/excel_handler.py

@@ -113,19 +113,23 @@ def write_markdown_consistency(ws, row_num, consistency_result):
     ws.cell(row=row_num, column=9, value=consistency_result)
 
 
-def write_formula_text(ws, row_num, file_path, source_dir="docs\\source", target_dir="docs\\target"):
+def write_formula_text(ws, row_num, file_path, source_dir=None, target_dir=None):
     """
     Write formula column
     
     Parameters:
         ws: Worksheet object
         row_num: Row number
         file_path: File path
-        source_dir: Source directory path
-        target_dir: Target directory path
+        source_dir: Source directory path (optional)
+        target_dir: Target directory path (optional)
     """
+    # Use provided directory names or default to generic names
+    source_dir_name = source_dir if source_dir else "source"
+    target_dir_name = target_dir if target_dir else "target"
+    
     # Generate formula text based on file path
-    formula_text = f"Compare {source_dir}\\{file_path} and {target_dir}\\{file_path} paragraph by paragraph with each heading as a paragraph, to ensure the target version is a complete and accurate translation of the source version."
+    formula_text = f"Compare {source_dir_name}\\{file_path} and {target_dir_name}\\{file_path} paragraph by paragraph with each heading as a paragraph, to ensure the target version is a complete and accurate translation of the source version."
     ws.cell(row=row_num, column=10, value=formula_text)
 
 

scripts/modules/main.py

@@ -6,23 +6,33 @@
 from .markdown_handler import compare_markdown_syntax_trees
 
 
-# Default directory and output file path
-source_dir = "g:\\temp\\defold_doc\\docs\\source"
-target_dir = "g:\\temp\\defold_doc\\docs\\target"
-output_file = "docs_structure_comparison_updated.xlsx"
-
-
 def main(source_dir_path=None, target_dir_path=None, output_file_path=None):
-    # Use passed parameters or default values
-    # Note: Keeping parameter names as source_dir_path and target_dir_path for clarity
-    if source_dir_path is None:
-        source_dir_path = globals().get('source_dir', "g:\\temp\\defold_doc\\docs\\source")
-        
-    if target_dir_path is None:
-        target_dir_path = globals().get('target_dir', "g:\\temp\\defold_doc\\docs\\target")
-        
+    """
+    Main function for document consistency checking
+    
+    Parameters:
+        source_dir_path: Source document directory path (required)
+        target_dir_path: Target document directory path (required)
+        output_file_path: Output Excel file path (optional, defaults to docs_structure_comparison.xlsx)
+    """
+    # Check if required parameters are provided
+    if source_dir_path is None or target_dir_path is None:
+        print("Error: Both source_dir_path and target_dir_path parameters are required.")
+        print("Usage: main(source_dir_path='path/to/source', target_dir_path='path/to/target')")
+        return
+    
+    # Check if directories exist
+    if not os.path.exists(source_dir_path):
+        print(f"Error: Source directory does not exist: {source_dir_path}")
+        return
+    
+    if not os.path.exists(target_dir_path):
+        print(f"Error: Target directory does not exist: {target_dir_path}")
+        return
+    
+    # Set default output file path if not provided
     if output_file_path is None:
-        output_file_path = globals().get('output_file', "docs_structure_comparison_updated.xlsx")
+        output_file_path = "docs_structure_comparison.xlsx"
 
     # Set console encoding to resolve character display issues
     setup_console_encoding()
@@ -113,4 +123,7 @@ def main(source_dir_path=None, target_dir_path=None, output_file_path=None):
 
 
 if __name__ == "__main__":
-    main()
+    # When run directly, provide usage information
+    print("This module is designed to be imported and used by docs_consistency_checker.py")
+    print("Usage: from main import main")
+    print("       main(source_dir_path='path/to/source', target_dir_path='path/to/target')")