Skip to content

README.md

Latest commit

 

History

History
88 lines (63 loc) · 4.13 KB

README.md

File metadata and controls

88 lines (63 loc) · 4.13 KB

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",
)
```

  1. 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.