Weblate Customize

This repository contains custom addons and file formats for Weblate, tailored for specific workflows such as VitePress documentation translation and advanced source-based component discovery.

Directory Structure

.
├── customize
│   ├── discovery.py    # Source-based component discovery addon
│   └── vitepress.py    # VitePress Markdown file format support

Features

1. Source-based Discovery (customize/discovery.py)

This module implements a custom Source Discovery Addon that allows you to discover translation components based on source file patterns using Regular Expressions.

Key Capabilities:

• Source File Matching: Uses regex to find source files (e.g., docs/guide/intro.md).
• Flexible Mapping: Supports regex capture groups to dynamically generate paths for translation files, component names, and base files.
• Categorization: Automatically assigns components to categories, formatted as Project Name / Category Name.
• Cleanup: Includes an "Uninstall & Remove" feature to safely delete components created by this addon.

2. VitePress Markdown Support (customize/vitepress.py)

This module provides a VitePress Markdown file format (vitepress-md) for Weblate.

Key Capabilities:

• Frontmatter Handling: Parses and translates YAML frontmatter (enclosed in ---) separately from the Markdown body.
• Bi-directional Sync:
  • Read: Extracts frontmatter keys and presents them as translation units.
  • Save: Reconstructs the file with translated frontmatter and content, preserving the original structure.
• Template Proxying: Hides frontmatter units from the standard Markdown parser to prevent parsing errors or duplicates.

Why not use standard Markdown?

Standard Markdown parsers in Weblate treat the file content as a single block or segment by paragraphs. However, VitePress and many static site generators rely heavily on YAML Frontmatter (metadata at the top of the file) for titles, descriptions, and configuration.

• Standard Markdown: Often ignores frontmatter or treats it as plain text, leading to broken formatting or untranslatable metadata.
• VitePress Markdown (This Plugin):
  1. Extracts Frontmatter: treats YAML keys as separate translation units, allowing you to translate page titles and SEO metadata.
  2. Protects Structure: Ensures the --- delimiters and YAML syntax remain intact after translation, preventing build errors.

Installation

To uses these customizations in your Weblate instance:

1. Mount/Copy Code: Ensure the customize directory is available in your Weblate environment's PYTHONPATH. Using a Docker volume mount is a common approach.

   # Example docker-compose volume
   volumes:
     - ./weblate-customize/customize:/app/data/python/customize

2. Configuration: If you are running Weblate with Docker, create or modify settings-override.py to register the custom addon:

   WEBLATE_ADDONS += (
       "customize.discovery.SourceDiscoveryAddon",
   )

   For the VitePress file format to be discovered, you must add it to WEBLATE_FORMATS in settings-override.py.

Important

Defining WEBLATE_FORMATS overrides the default supported formats. To retain support for standard formats (like Gettext, XLIFF, etc.), you must manually include them in your list.

Please consult FormatsConf.FORMATS in weblate/formats/models.py to find the default formats and include them in your configuration.

```python
WEBLATE_FORMATS = (
    # ... Add default formats found in Weblate source code ...
    
    # Add Custom Format
    "customize.vitepress.VitePressMarkdownFormat",
)
```

3. Usage:

   • Discovery: Go to a Component -> Addons -> Source-based Discovery. Configure the regex patterns.
   • File Format: When creating a component, select "VitePress Markdown" as the file format.

License

This project is licensed under the GNU General Public License v3.0.