Pology User Manual
     Next

Pology User Manual

Chusslove Illich

Abstract

Pology is a Python library and collection of scripts for in-depth processing of PO files. The library is designed for easy and robust writing of custom scripts in field environments. The scripts perform wide variety of tasks, from precision operations on individual messages in PO files, to cross-file operations on large collections of PO files. Special support is provided for common elements in PO translation workflow, such as translation editors and version control systems, as well as for language-specific and project-specific needs.

This document is the referent source of information on Pology. It describes the functionality available to end users, but also gives the overview of programming with Pology, since Pology is easily extensible and users are encouraged to introduce their own processing elements.

1. A Study of PO
1.1. Obtaining and Installing
1.2. Dependencies
2. The PO Format
2.1. Basic Syntax
2.1.1. Source References
2.1.2. String Wrapping
2.1.3. Uniqueness of Messages
2.2. Message Context
2.2.1. Extracted Comments
2.2.2. Disambiguating Contexts
2.2.3. Translator Comments
2.3. Constructive Substrings
2.3.1. Format Directives
2.3.2. Text Markup
2.3.3. Escape Sequences
2.3.4. Accelerators
2.4. Plural Forms
2.4.1. Omitting The Number
2.5. Merging With Templates
2.5.1. Fuzzy Messages
2.5.2. Treatment of Fuzzy Messages
2.5.3. Obsolete Messages
2.5.4. Starting a New PO file
2.6. PO Header
2.7. Representation in Editors
2.7.1. List of PO Editors
3. Sieving
3.1. Basic Usage of posieve
3.2. Sieve Chains
3.3. Command Line Options
3.4. User Configuration
3.5. Internal Sieves
3.5.1. apply-filter
3.5.2. apply-header-filter
3.5.3. bad-patterns
3.5.4. check-docbook4
3.5.5. check-grammar
3.5.6. check-kde4
3.5.7. check-rules
3.5.8. check-spell
3.5.9. check-spell-ec
3.5.10. check-tp-kde
3.5.11. check-tp-wesnoth
3.5.12. collect-pmap
3.5.13. diff-previous
3.5.14. empty-fuzzies
3.5.15. equip-header-tp-kde
3.5.16. fancy-quote
3.5.17. find-messages
3.5.18. generate-xml
3.5.19. merge-corr-tree
3.5.20. normalize-header
3.5.21. normctxt-delim
3.5.22. normctxt-sep
3.5.23. remove-fuzzy-comments
3.5.24. remove-obsolete
3.5.25. remove-previous
3.5.26. resolve-aggregates
3.5.27. resolve-alternatives
3.5.28. resolve-entities
3.5.29. set-header
3.5.30. stats
3.5.31. tag-untranslated
3.5.32. unfuzzy-context-only
3.5.33. unfuzzy-ctxmark-only
3.5.34. unfuzzy-inplace-only
3.5.35. unfuzzy-qtclass-only
3.5.36. update-header
3.5.37. fr:setUbsp
3.5.38. ru:fill-doc-date-kde
3.6. Using External Sieves
4. Diffing and Patching
4.1. The Embedded Diff Format
4.1.1. Embedding Differences into Strings
4.1.2. Message Parts Included in Diffing
4.1.3. Pairing Messages From Two PO Files
4.1.4. Collecting Diffed Messages
4.2. Producing Ediffs with poediff
4.2.1. Diffing With Underlying VCS
4.2.2. Command Line Options
4.2.3. User Configuration
4.3. Applying Ediffs as Patches with poepatch
4.3.1. Handling Rejected Ediffs
4.3.2. Embedding Patches
4.3.3. Command Line Options
4.3.4. User Configuration
5. Summitting Translation Branches
5.1. Setting Up The Summit with posummit
5.1.1. Setting Up Direct Summit
5.1.2. Setting Up Summit over Dynamic Templates
5.1.3. Setting Up Summit over Static Templates
5.1.4. Transforming Branch Paths
5.2. Maintaining the Summit
5.2.1. Centralized Summit Maintenance
5.2.2. Distributed Summit Maintenance
5.2.3. Handling Mismatches Between Branches and Summit
5.2.4. Checking Summit Dependencies
5.3. Elements of Summit Configuration
5.3.1. Summit Hooks
5.3.2. Integration with Version Control Systems
5.3.3. Text Wrapping in PO Files
5.3.4. Vivification of Summit PO Files
5.3.5. Merging in Branches
5.3.6. Propagation of Header Parts
5.3.7. Filtering by Ascription on Scatter
5.3.8. Other Branch Options
5.3.9. Other Merge Options
5.3.10. Other Scatter Options
5.4. Disadvantages to Summit Workflow and Remedies
6. Ascribing Modifications and Reviews
6.1. Review Stages vs. Ascription
6.2. Setting up Ascription with poascribe
6.2.1. Initial Ascription
6.3. Daily Use for Translators
6.3.1. Translators Without Commit Access
6.4. Daily Use for Reviewers
6.4.1. Basic Reviewing
6.4.2. Selecting Messages for Review
6.4.3. Fine-Grained Reviews
6.5. General Maintenance Procedures
6.5.1. Ascribing Merges
6.5.2. Shuffling Ascription PO Files
6.5.3. Filtering for Release
6.5.4. Trimming Ascription History
6.6. Command Line Options
6.7. User Configuration
6.8. Review Selectors
6.8.1. Custom Review Selectors
7. Miscellaneous Tools
7.1. Rewrapping PO Files with porewrap
7.1.1. Command Line Options
7.1.2. User Configuration
7.2. Self-Merging PO Files with poselfmerge
7.2.1. Command Line Options
7.2.2. User Configuration
7.3. Machine Translation with pomtrans
7.3.1. Command Line Options
7.3.2. Supported Machine Translation Services
8. Language Validation and Derivation
8.1. The Notion of Language in Pology
8.1.1. Supported Languages and Environments
8.2. Spell Checking
8.2.1. Internal Spelling Dictionaries
8.2.2. Skipping Messages and Words
8.3. Grammar Checking
8.4. Automatic Insertion of UI Labels
8.4.1. Wrapping UI References
8.4.2. Normalization of UI Text
8.4.3. Linking to Originating PO Files
8.4.4. Notes on UI Reference Resolution
8.5. Validation Rules
8.5.1. Guided Tour of the Rule System
8.5.2. Layout of Rule Files
8.5.3. Rule Triggers
8.5.4. Rule Subdirectives
8.5.5. Global Directives in Rule Files
8.5.6. Effect of Rule Environments
8.5.7. Filtering Messages
8.5.8. Quoting and Escaping
8.5.9. Canceling False Positives
8.6. Syntagma Derivation
8.6.1. Basic Derivations
8.6.2. Multiple Expansions
8.6.3. Expansion Masks
8.6.4. Special Properties
8.6.5. Text Tags
8.6.6. Alternative Derivations
8.6.7. Treatment of Whitespace
8.6.8. Uniqueness, Ordering, and Inclusions
8.6.9. Error Handling
9. Common Functionality
9.1. Shell Completion
9.2. User Configuration
9.2.1. The [global] section
9.2.2. The [user] section
9.2.3. The [enchant] section
9.2.4. The [aspell] section
9.2.5. Per-project sections ([project-*])
9.3. Regular Expressions
9.4. Path Inclusion and Exclusion
9.5. Reading Paths From a File
9.6. Output Coloring
9.7. Integration with Other Tools
9.7.1. PO Editors
9.7.2. Version Control Systems
9.8. Line Wrapping in PO Messages
9.8.1. Common Command Line Options for Wrapping
9.8.2. Common User Configuration Fields for Wrapping
9.9. Influential Header Fields
9.10. Processing Hooks
9.10.1. Hook Types
9.10.2. List of Internal Hooks
9.10.3. Using External Hooks
9.11. Skipping and Selecting Checks
10. Combined Arms Tactics
10.1. Creating and Using PO Compendia
10.1.1. Why Translation Memory?
10.1.2. Maintaining a Centralized PO Compendium
10.1.3. Applying the PO Compendium
10.2. Efficiently Translating with a Text Editor
10.2.1. Expected Features of the Text Editor
10.2.2. Statistics on PO Files
10.2.3. Updating PO Files After Merging
10.3. Summit with Ascription
10.3.1. Several Summits with Unified Ascription
11. Programming with Pology
11.1. PO Format Abstraction
11.1.1. Monitored Objects
11.1.2. Message
11.1.3. Header
11.1.4. Catalog
11.2. Coding Conventions
11.2.1. User-Visible Text and Internationalization
11.3. Writing Sieves
11.3.1. Sieve Layout
11.3.2. Sieve Parameter Handling
11.3.3. Catalog Regime Indicators
11.3.4. Further Notes on Sieves
11.4. Writing Hooks
11.4.1. Hook Taxonomy
11.4.2. Hook Factories
11.4.3. Further Notes on Hooks
11.5. Writing Ascription Selectors
     Next
     Chapter 1. A Study of PO