Skip to content

Commit ef54cea

Browse files
polprog-devpolprog-dev
committed
feat: initial LocaleSync implementation
Signed-off-by: Damian Skrzyński <polprog.tech@gmail.com>
1 parent f3c3ac7 commit ef54cea

104 files changed

Lines changed: 10323 additions & 1 deletion

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.devcontainer/devcontainer.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "LocaleSync",
3+
"image": "mcr.microsoft.com/devcontainers/python:3.12",
4+
"postCreateCommand": "pip install -e '.[dev]'",
5+
"customizations": {
6+
"vscode": {
7+
"extensions": [
8+
"ms-python.python",
9+
"charliermarsh.ruff"
10+
],
11+
"settings": {
12+
"python.testing.pytestEnabled": true,
13+
"python.testing.pytestArgs": ["tests"]
14+
}
15+
}
16+
}
17+
}

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug in LocaleSync
4+
title: "[Bug] "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## Describe the Bug
10+
11+
A clear and concise description of what the bug is.
12+
13+
## To Reproduce
14+
15+
Steps to reproduce the behavior:
16+
17+
1. Run `locale-sync ...`
18+
2. With these locale files: (attach or describe)
19+
3. Observe the error
20+
21+
## Expected Behavior
22+
23+
A clear description of what you expected to happen.
24+
25+
## Actual Behavior
26+
27+
What actually happened. Include full command output if possible.
28+
29+
## Environment
30+
31+
- **OS:** (e.g., macOS 14, Ubuntu 22.04)
32+
- **Python version:** (e.g., 3.12.1)
33+
- **LocaleSync version:** (run `locale-sync --version`)
34+
- **Installation method:** (pip install, editable, etc.)
35+
36+
## Additional Context
37+
38+
Add any other context, locale file examples, or screenshots.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Feature Request
3+
about: Suggest a new feature or improvement
4+
title: "[Feature] "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## Problem / Motivation
10+
11+
Describe the problem or need this feature would address.
12+
13+
## Proposed Solution
14+
15+
A clear description of what you'd like to happen.
16+
17+
## Alternatives Considered
18+
19+
Any alternative solutions or workarounds you've considered.
20+
21+
## Additional Context
22+
23+
Examples, mockups, or references to similar features in other tools.

‎.github/pull_request_template.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## Description
2+
3+
Brief description of what this PR does.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix (non-breaking change that fixes an issue)
8+
- [ ] New feature (non-breaking change that adds functionality)
9+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
10+
- [ ] Documentation update
11+
- [ ] Refactoring (no functional changes)
12+
13+
## Changes Made
14+
15+
- Change 1
16+
- Change 2
17+
18+
## How to Test
19+
20+
Steps to verify this change:
21+
22+
1. `pip install -e ".[dev]"`
23+
2. `pytest`
24+
3. (any specific commands to test the change)
25+
26+
## Checklist
27+
28+
- [ ] My code follows the project's architecture (domain/application/infrastructure/cli layers)
29+
- [ ] I have added tests that cover my changes
30+
- [ ] All new and existing tests pass (`pytest`)
31+
- [ ] I have updated documentation if needed
32+
- [ ] My changes produce no new linting warnings (`ruff check src/ tests/`)

‎.github/workflows/ci.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
test:
14+
name: Test (Python ${{ matrix.python-version }})
15+
runs-on: ubuntu-latest
16+
strategy:
17+
fail-fast: false
18+
matrix:
19+
python-version: ["3.12", "3.13"]
20+
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Set up Python ${{ matrix.python-version }}
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: ${{ matrix.python-version }}
28+
29+
- name: Install dependencies
30+
run: pip install -e ".[dev]"
31+
32+
- name: Run tests
33+
run: pytest --tb=short -q
34+
35+
- name: Run tests with coverage
36+
run: pytest --cov=locale_sync --cov-report=term-missing --tb=short -q
37+
38+
lint:
39+
name: Lint
40+
runs-on: ubuntu-latest
41+
42+
steps:
43+
- uses: actions/checkout@v4
44+
45+
- name: Set up Python
46+
uses: actions/setup-python@v5
47+
with:
48+
python-version: "3.12"
49+
50+
- name: Install dependencies
51+
run: pip install -e ".[dev]"
52+
53+
- name: Run ruff check
54+
run: ruff check src/ tests/
55+
56+
- name: Run ruff format check
57+
run: ruff format --check src/ tests/
58+
59+
check-translations:
60+
name: Check Translations (Playground)
61+
runs-on: ubuntu-latest
62+
63+
steps:
64+
- uses: actions/checkout@v4
65+
66+
- name: Set up Python
67+
uses: actions/setup-python@v5
68+
with:
69+
python-version: "3.12"
70+
71+
- name: Install LocaleSync
72+
run: pip install -e .
73+
74+
- name: Scan playground locales
75+
run: locale-sync scan playground/locales
76+
77+
- name: Check playground locales
78+
run: locale-sync check playground/locales || true # Expected to find missing keys

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
__pycache__/
2+
*.py[cod]
3+
*$py.class
4+
*.egg-info/
5+
dist/
6+
build/
7+
.eggs/
8+
*.egg
9+
.pytest_cache/
10+
.coverage
11+
htmlcov/
12+
.ruff_cache/
13+
*.bak
14+
.venv/
15+
venv/
16+
node_modules/

‎CODE_OF_CONDUCT.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to a positive environment:
15+
16+
* Using welcoming and inclusive language
17+
* Being respectful of differing viewpoints and experiences
18+
* Gracefully accepting constructive criticism
19+
* Focusing on what is best for the community
20+
* Showing empathy towards other community members
21+
22+
Examples of unacceptable behavior:
23+
24+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
25+
* Trolling, insulting/derogatory comments, and personal or political attacks
26+
* Public or private harassment
27+
* Publishing others' private information without explicit permission
28+
* Other conduct which could reasonably be considered inappropriate in a professional setting
29+
30+
## Enforcement
31+
32+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
33+
reported to the project maintainers. All complaints will be reviewed and
34+
investigated and will result in a response that is deemed necessary and
35+
appropriate to the circumstances.
36+
37+
## Attribution
38+
39+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to LocaleSync
2+
3+
Thank you for your interest in contributing! This document provides guidelines and information for contributors.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
- Python 3.12 or higher
10+
- Git
11+
12+
### Setting Up the Development Environment
13+
14+
```bash
15+
# 1. Clone the repository
16+
git clone https://github.com/polprog-tech/LocaleSync.git
17+
cd LocaleSync
18+
19+
# 2. (Recommended) Create a virtual environment
20+
python3 -m venv .venv
21+
source .venv/bin/activate # Linux/macOS
22+
# .venv\Scripts\activate # Windows
23+
24+
# 3. Install in editable mode with dev dependencies
25+
pip install -e ".[dev]"
26+
27+
# 4. Verify the installation
28+
locale-sync --version
29+
pytest
30+
```
31+
32+
## Development Workflow
33+
34+
### Running Tests
35+
36+
```bash
37+
# All tests
38+
pytest
39+
40+
# With verbose output
41+
pytest -v
42+
43+
# With coverage
44+
pytest --cov=locale_sync --cov-report=term-missing
45+
46+
# Specific test file or class
47+
pytest tests/unit/domain/test_models.py
48+
pytest tests/unit/domain/test_models.py::TestLocaleKey
49+
```
50+
51+
### Linting
52+
53+
```bash
54+
ruff check src/ tests/
55+
ruff format --check src/ tests/
56+
57+
# Auto-fix
58+
ruff check --fix src/ tests/
59+
ruff format src/ tests/
60+
```
61+
62+
### Testing with the Playground
63+
64+
```bash
65+
locale-sync scan playground/locales
66+
locale-sync check playground/locales
67+
locale-sync sync playground/locales --dry-run
68+
```
69+
70+
## Architecture
71+
72+
Please read [docs/architecture.md](docs/architecture.md) before making changes. Key principles:
73+
74+
1. **Domain layer** (`src/locale_sync/domain/`) has zero external dependencies
75+
2. **Application layer** orchestrates but does not import infrastructure directly at module level
76+
3. **Infrastructure layer** implements domain contracts (Protocols)
77+
4. **CLI layer** is a thin adapter between user input and application use cases
78+
79+
### Where to Put New Code
80+
81+
| What | Where |
82+
|------|-------|
83+
| New model/value object | `domain/models.py` |
84+
| New contract/interface | `domain/contracts.py` |
85+
| New exception type | `domain/exceptions.py` |
86+
| New file format parser | `infrastructure/parsers/` |
87+
| New file format writer | `infrastructure/writers/` |
88+
| New translation provider | `infrastructure/translators/` |
89+
| New report format | `infrastructure/reporters/` |
90+
| New CLI command | `cli/commands/` |
91+
| New use case | `application/` |
92+
93+
### Adding a Translation Provider
94+
95+
See [docs/extensibility.md](docs/extensibility.md) for detailed guidance.
96+
97+
## Pull Request Process
98+
99+
1. Fork the repository and create a feature branch from `main`
100+
2. Make your changes following the architecture guidelines
101+
3. Add tests for new functionality
102+
4. Ensure all tests pass: `pytest`
103+
5. Ensure linting passes: `ruff check src/ tests/`
104+
6. Update documentation if needed
105+
7. Submit a pull request using the PR template
106+
107+
### Commit Messages
108+
109+
Use conventional commit style:
110+
111+
```
112+
feat: add YAML format support
113+
fix: handle empty nested objects in JSON parser
114+
docs: update extensibility guide with YAML example
115+
test: add edge case tests for placeholder detection
116+
refactor: extract common file resolution logic
117+
```
118+
119+
## Code Style
120+
121+
- Full type hints on all function signatures
122+
- Docstrings on public classes and functions
123+
- Use `from __future__ import annotations` in all modules
124+
- Follow existing patterns in the codebase
125+
- Let `ruff` handle formatting
126+
127+
## Reporting Issues
128+
129+
Use the GitHub issue templates:
130+
- **Bug reports** — include reproduction steps, expected vs actual behavior, and environment details
131+
- **Feature requests** — describe the problem, proposed solution, and alternatives considered
132+
133+
## License
134+
135+
By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).

0 commit comments

Comments
 (0)