Imported from git-l10n/git-po-helper (AGENTS.md). Install upstream with npx skills add git-l10n/git-po-helper. Copyright stays with the author.

AGENTS.md - git-po-helper Project Guide

Project Overview

git-po-helper is a command-line tool written in Go for checking conventions for Git localization (l10n) contributions. This project provides automated checking tools for Git l10n coordinators and contributors, ensuring that pull requests submitted to git-l10n/git-po comply with established contribution conventions.

Technology Stack

• Programming Language: Go 1.16+
• CLI Framework: spf13/cobra - For building command-line interfaces
• Configuration Management: spf13/viper - Configuration and flag management
• Logging: sirupsen/logrus - Structured logging
• Other Dependencies:
  • github.com/gorilla/i18n - Internationalization support
  • github.com/qiniu/iconv - Character encoding conversion
  • github.com/mattn/go-isatty - Terminal detection
  • github.com/jiangxin/goconfig - Configuration handling

Project Architecture

The project follows a standard Go project structure:

• cmd/ - CLI subcommand implementations (check-commits, check-po, compare, agent-run, agent-test, msg-cat, msg-select, team, update, version)
• util/ - Core utility functions and business logic
• data/ - ISO-3166 and ISO-639 language/country code data (generated from CSV)
• dict/ - Spell checking and smudge rules for various languages
• gettext/ - gettext-related functionality
• repository/ - Git repository operations wrapper
• version/ - Version information management
• flag/ - Command-line flag handling
• contrib/ - Contributing tools and scripts
• test/ - Integration test suite (using git test-lib framework)

Build and Run

Prerequisites

Before compiling git-po-helper, the following dependencies must be installed:

• Go: Version 1.16 or higher
• git: Git version control system
• gettext: For processing .po files
• iconv: For checking commit log encoding
• gpg: For verifying GPG-signed commits

Build Commands

# Clone the repository
git clone https://github.com/git-l10n/git-po-helper.git
cd git-po-helper

# Build the project
make

# Run tests (including unit tests and integration tests)
make test

# Run unit tests only
make ut

# Run integration tests only
make it

# Run code linting
make lint

Installation

After compilation, copy the binary to a system path:

cp git-po-helper /usr/local/bin/

Main Makefile Targets

• make or make all - Build the git-po-helper binary
• make test - Run the complete test suite (including lint, unit tests, and integration tests)
• make ut - Run unit tests only
• make it - Run integration tests only
• make lint - Run static code analysis (go vet and staticcheck)
• make clean - Clean build artifacts

Version Management

The project uses automatically generated version files:

• VERSION-FILE - Generated by the VERSION-GEN script
• Version information is injected into the binary via -ldflags

Development Standards

Code Style

1. Go Standard Format: Follow Go's official code formatting standards
2. Package Structure:
   • The cmd/ package contains all CLI command implementations
   • The util/ package contains reusable utility functions
   • Each package has clear responsibility boundaries
3. Error Handling: Use custom commandError type to distinguish user errors from system errors
4. Logging Levels: Support quiet (-q) and verbose (-v) modes, using logrus for structured logging

Testing Practices

1. Unit Tests:

   • Use Go's standard testing framework
   • Test files end with _test.go
   • Run command: make ut

2. Integration Tests:

   • Use git test-lib framework (located in test/lib/)
   • Test scripts are in the test/ directory
   • Test cases follow the t*.sh naming convention
   • Run command: make it

3. Code Quality Checks:

   • Use go vet for static analysis
   • Use staticcheck for deeper code inspection
   • Run command: make lint

Main Functional Modules

Command List

• agent-run - Run agent commands for automation (update-pot, update-po, translate, review, report)
• agent-test - Test agent commands with multiple runs
• check-commits - Check if commits comply with l10n conventions
• check-po - Check syntax of XX.po or XX.pot file (for Git .pot, also checks CamelCase config variables; requires Documentation/config)
• compare - Show differences between two l10n files (--stat for diff stats, or new/changed entries)
• msg-cat - Concatenate and merge PO/POT/JSON files (first occurrence of each msgid wins)
• msg-select - Extract entries from PO/POT file by index range
• team - Show team leader/member information
• update - Update XX.po file
• version - Display version information

Core Checking Features

The project primarily checks the following Git l10n contribution conventions:

1. File Location: Only files in the po/ directory are allowed to be modified
2. Commit Log Format:
   • Subject must start with the "l10n:" prefix
   • Subject must not contain non-ASCII characters
   • Subject length must not exceed 50 characters
   • Other lines must not exceed 72 characters
   • Must include "Signed-off-by:" signature
3. .po File Syntax: Use msgfmt to verify syntax correctness
4. Completeness: Ensure all translatable strings are present in po/XX.po
5. File Location Cleanup: File location information must be removed before submission
6. Spell Checking: Check for common spelling errors (supports multiple languages)

Data Generation

The project includes mechanisms for generating Go code from CSV files:

• data/iso-3166.go - Generated from data/iso-3166.csv
• data/iso-639.go - Generated from data/iso-639.csv
• Generated using the go generate command

Contribution Guidelines

Although the project doesn't have an explicit CONTRIBUTING.md, the following can be inferred from the code structure:

1. Commit Standards: Follow the project's commit log format requirements
2. Testing Requirements: New features must include corresponding test cases
3. Code Review: Automated checks through CI/CD processes (GitHub Actions)
4. Backward Compatibility: Maintain compatibility with older versions of gettext

Commit Conventions

• Specification: Commit messages MUST follow the Conventional Commits Specification.
• Language: Commit messages MUST be written in English.
• Multi-line structure: A good commit message SHOULD contain multiple lines: the first line is the subject, the second line is blank, and the third and subsequent lines contain a detailed description of the change.
• Content focus: The detailed description MUST explain the reasons for the change (why) and include a concise description of what was changed, rather than only describing how the change was implemented (how).
• Inferring reasons: The reasons for the change SHOULD be inferred from the prompts together with the actual code changes.
• Line length: No single line in the commit message SHOULD exceed 72 characters. If a line would be longer, wrap it to the next line without inserting extra blank lines.
• HereDoc usage: When running the git commit command, use a HereDoc to provide the commit message, for example: git commit -F- <<-EOF, and do NOT use multiple -m <message> arguments to build a multi-line commit message, because multiple -m <message> options will insert redundant blank lines into the final commit message.

Configuration

The project supports configuration through:

• Command-line flags (using Cobra and Viper)
• Environment variables (supported via Viper)
• Configuration files (if Viper configuration files are set up)

Special Features

1. GitHub Actions Integration: Support for running in GitHub Actions environments
2. Multi-language Support: Includes spell checking and smudge rules for multiple languages (bg, ca, de, es, fr, it, ko, pt, sv, tr, vi, etc.)
3. POT File Handling: Supports automatic download, build, or use of local POT files
4. GPG Verification: Optional GPG signature verification feature

Use Cases

This tool is primarily used for:

1. Git l10n Coordinators: Automatically check if submitted pull requests comply with conventions
2. Git l10n Contributors: Locally check if their contributions meet requirements before submission
3. CI/CD Workflows: Integration into automated workflows for continuous checking

Related Resources

• Project Repository: https://github.com/git-l10n/git-po-helper
• Git l10n Repository: https://github.com/git-l10n/git-po
• POT File Source: https://github.com/git-l10n/pot-changes
• Git Project Documentation: https://github.com/git/git/tree/master/po