Metadata-Version: 2.1
Name: poglossary
Version: 0.1.3
Summary: A CLI tool that scans through .po files and searches for mistranslated terms based on user-defined glossary mapping
License: MIT
Author: Matt.Wang
Author-email: mattwang44@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: polib (>=1.1.1,<2.0.0)
Requires-Dist: pydantic (>=1.9.0,<2.0.0)
Requires-Dist: tabulate[widechars] (>=0.8.9,<0.9.0)
Requires-Dist: typer[all] (>=0.4.0,<0.5.0)
Description-Content-Type: text/markdown

# poglossary

[![Python](https://img.shields.io/pypi/pyversions/poglossary.svg?style=plastic)](https://badge.fury.io/py/poglossary)
[![PyPI](https://badge.fury.io/py/poglossary.svg)](https://badge.fury.io/py/poglossary)

A CLI tool that scans through translation project (`.po` files) searching for mistranslated terms based on the user-defined glossary mapping.

This project is specially tailored for [Python Documentation Translation Project (zh_TW)](https://github.com/python/python-docs-zh-tw) but can be applied for all translation projects that adopt Portable Object files (`.po`).

## Install

To install the current release:

```sh
pip3 install poglossary
```

To update it to the latest version, add `--upgrade` flag to the above commands.

Run `poglossary --help` and you should see the following output if it's installed sucessfully.

```sh
poglossary --help
# Usage: poglossary [OPTIONS] [PATH] [CONFIG_FILE]

#   poglossary: check translated content in .po files based on given translation
#   mapping

# Arguments:
#   [PATH]         the path of the directory storing .po files  [default: .]
#   [CONFIG_FILE]  input mapping file  [default: ./poglossary.yml]

# Options:
#   --excludes PATH       the directories that need to be omitted
#   --install-completion  Install completion for the current shell.
#   --show-completion     Show completion for the current shell, to copy it or
#                         customize the installation.
#   --help                Show this message and exit.
```

## Usage

### Config File

A config file in YAML format is required for poglossary, only the following two keys are recognized:

- `glossary` (required): A mapping of untrnaslated term to translated term. The value can be a list if it has multiple translation choices.
- `ignore` (optional): If skipping the checking for specific regex patterns or rST syntax is wanted, add the key `patterns` or `rst_tags` as the example below.

```yml
# Sample config file (.yml)
glossary:
  exception: 例外
  function: 函式
  instance: 實例
  type: # can be a list of possible translated terms of "type"
    - 型別
    - 種類

ignore:
  patterns:
    - "type code(s)?" # "type code" or "type codes" will be skipped
  rst_tags:
    - source # skip :source:`*`
    - class
    - c:
        - func # -> skip :c:func:`*`
        - data
```

or you can checkout a more detailed configuration in [poglossary.example.yml](./poglossary.example.yml) (, which is the config tend to be used in [pydoc-zhtw](https://github.com/python/python-docs-zh-tw)).

### Command

```shell
poglossary <source_path> <config_file>
```

`poglossary` takes in two optional arguments:

- `source_path`: It can be the path of the target PO file or a directory that stores PO files. Defaults to `.`.
- `config_file`: The path of the config file. Defaults to `./poglossary.yml`.

The sample output is shown below:

![image](https://user-images.githubusercontent.com/24987826/149608253-bec9d2ed-6605-41c8-956c-5e23e8447a5d.png)

## Todo

- [ ] Functionality
  - [ ] More handy parameters/options
- [ ] CI/CD
  - [ ] Unit tests
  - [ ] Static checks (mypy, isort, etc)
  - [ ] Upload to PyPI
- [ ] Config files
  - [ ] Handle missing fields.
  - [ ] Commands for creating a basic config file.

