docs: rewrite README and CONTRIBUTING with full usage guide

README.md:
- Add uvx usage instructions
- Document required GitHub token scopes (user + repo)
- Add contributors section
- Add Apache 2.0 license notice
- Use emojis on all level-2 headers

CONTRIBUTING.md:
- Integrate TRANSLATIONS.md content (now deleted)
- Document all poe dev commands (lint, lint:format, lint:types, test)
- Add Conventional Commits reference table and examples
- Add release cycle section (poe release, git push --tags)
- Add pre-commit install instructions including commit-msg hook

Author: zodiacfireworks

CONTRIBUTING.md

@@ -1,46 +1,138 @@
-# Developer Guide
+# 🛠️ Developer Guide
 
-This document will explain how to contribute to the edit-python.pe project.
+This document explains how to contribute to the edit-python.pe project, the commands needed for development, and the translation workflow.
 
-## How to Contribute
+## 🤝 How to Contribute
 
-1. Make sure to find an open issue on [GitHub](https://github.com/python.pe/edit-python.pe/issues).
-1. Fork the [edit-python.pe](https://github.com/python.pe/edit-python.pe) repository.
-1. Clone the forked repository to your local machine.
-1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
-1. Install dependencies:
+1. Make sure to find an open issue on [GitHub](https://github.com/pythonpe/edit-python.pe/issues).
+2. Fork the [edit-python.pe](https://github.com/pythonpe/edit-python.pe) repository.
+3. Clone the forked repository to your local machine.
+4. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+5. Install dependencies:
+   ```bash
+   uv sync
+   ```
+6. Install the pre-commit hooks (enforces conventional commits and quality checks):
+   ```bash
+   uv run pre-commit install --hook-type commit-msg
+   uv run pre-commit install
+   ```
+7. Make your changes and cover them with tests.
+8. Push your changes to the forked repository.
+9. Open a pull request on [GitHub](https://github.com/pythonpe/edit-python.pe/pulls).
+
+## 🚀 Development Commands
+
+We use `poethepoet` (poe) as our task runner. Run the following commands as needed during development:
+
+- `uv run poe lint`: Runs the `ruff` linter (and checks types using `ty`).
+- `uv run poe lint:format`: Formats the code using `ruff format`.
+- `uv run poe lint:types`: Checks types using `ty check`.
+- `uv run poe test`: Runs the test coverage with `pytest`.
+
+## 📝 Commit Style (Conventional Commits)
+
+This project enforces [Conventional Commits](https://www.conventionalcommits.org/) via a pre-commit hook powered by [Commitizen](https://commitizen-tools.github.io/commitizen/). Every commit message **must** follow this format:
+
+```
+<type>(<optional scope>): <short description>
+```
+
+Allowed types:
+
+| Type | When to use |
+|------|-------------|
+| `feat` | A new feature |
+| `fix` | A bug fix |
+| `docs` | Documentation only changes |
+| `style` | Code style changes (formatting, missing semicolons, etc.) |
+| `refactor` | Code change that is neither a fix nor a feature |
+| `perf` | A code change that improves performance |
+| `test` | Adding or fixing tests |
+| `build` | Changes to build system or dependencies |
+| `ci` | Changes to CI configuration files and scripts |
+| `chore` | Other changes that don't modify source or test files |
+
+**Examples:**
+```
+feat(auth): add GitHub OAuth login
+fix(markdown): handle missing homepage field gracefully
+docs: update README with uvx usage
+```
+
+You can use `uv run cz commit` as an interactive guided commit helper instead of `git commit`.
+
+## 🏷️ Release Cycle
+
+Releases are managed by [Commitizen](https://commitizen-tools.github.io/commitizen/), which automatically:
+
+- Determines the next semantic version from the commit history (`feat` → minor bump, `fix` → patch bump, `feat!` or `BREAKING CHANGE` → major bump).
+- Updates the version in `pyproject.toml` and `src/edit_python_pe/__version__.py`.
+- Generates or appends to `CHANGELOG.md`.
+- Creates a git tag `v<version>`.
+
+### Performing a Release
+
+> **Only maintainers** should run this command on the `main` branch.
 
 ```bash
-uv sync
+uv run poe release
 ```
 
-1. Install pre-commit hook:
+This runs `cz bump --changelog` under the hood. After the tag is created, push both the commit and the tag:
 
 ```bash
-uv run pre-commit install
+git push && git push --tags
 ```
 
-1. Make your changes.
-1. Cover your changes with tests.
-1. Run the test coverage:
+### Previewing the Changelog
+
+To regenerate or preview the full changelog without bumping the version:
+
+```bash
+uv run poe release:changelog
+```
+
+## 🌐 Translation Workflow
+
+This project uses `pybabel` for translations, completely managed through `poe` tasks. The translation files are packaged internally within `src/edit_python_pe/locale/` so they are automatically included in PyPI wheel distributions.
+
+### 1. Generating or Updating `.po` files
+
+When you add new `_("...")` strings in the source code, run:
+
+```bash
+uv run poe messages:update
+```
+
+This automatically extracts all translation strings from `src/edit_python_pe/` into `messages.pot` and **updates all existing locales** (e.g. `es`, `fr`, etc.) with the new strings, keeping existing translations intact.
+
+If you only want to extract strings to `messages.pot` without updating the language files, run:
 
 ```bash
-uv run poe test
+uv run poe messages:extract
 ```
 
-1. Run the auto-translations:
+> **Note:** We have removed automated machine translation scripts. Automatic tools often miss context-specific terminology (for example, translating "Save" as "Ahorro" instead of "Guardar"). You **must** review the `.po` files one by one and translate them manually, ensuring the correct context for the application.
+
+### 2. Compiling `.mo` files
+
+After you finish manually translating the `.po` files, you must compile them into the binary `.mo` format so the application can read them.
 
 ```bash
-uv run poe makemessages
+uv run poe messages:compile
 ```
 
-1. Commit your changes, if the pre-commit hook fails, run `uv run poe test` to
-   know which test failed.
-1. If the last step was your last commit on this issue, run this command:
+This command compiles all languages in the `locale` directory simultaneously.
+
+---
+
+### Adding a New Language
+
+If you want to add an entirely new language (for example, German `de`), use the `messages:init` command:
 
 ```bash
-uv run poe version:update NEW_VERSION
+uv run poe messages:init --lang de
 ```
 
-1. Push your changes to the forked repository.
-1. Open a pull request on [GitHub](https://github.com/python.pe/edit-python.pe/pulls).
+This extracts the strings and initializes the completely new directory `src/edit_python_pe/locale/de/LC_MESSAGES/messages.po`.

README.md

@@ -1,40 +1,44 @@
 # edit-python.pe
 
-## *Textual Tool for Creating Member Profiles for python.pe*
+## 🚀 Textual Tool for Creating Member Profiles for python.pe
 
-This tutorial will guide you step-by-step to create your profile on python.pe
-quickly and securely.
+This tool will guide you step-by-step to create your profile on python.pe quickly and securely directly from your terminal!
 
-## Prerequisites
+## 📋 Prerequisites
+
+To use `edit-python.pe`, ensure you have [`uv`](https://docs.astral.sh/uv/) installed:
 
 ```bash
 # Check required versions
 uv --version # >= 0.8.11
 ```
 
-## Installing edit-python.pe
+## 💻 Usage
 
-### Installing dependencies
+For users seeking maximum speed and ease, you can run the tool directly using `uvx` without explicitly installing or cloning the repository:
 
 ```bash
-uv sync
+uvx edit-python-pe
 ```
 
-### **Creating the access token**
+Next, you'll be prompted for your access token and then you can seamlessly edit your member profile.
 
-1. Generate a [Personal access token
-(classic)](https://github.com/settings/tokens).
-1. Grant the scope: `public_repo`.
-1. Copy the token and keep it handy for the command below
+## 🔑 Creating the GitHub Access Token
 
-### **For users seeking maximum speed**
+To interact with the repository and submit your profile, you will need a GitHub Personal Access Token.
 
-```bash
-uvx edit-python-pe
-# Next you'll be prompted for your access token
-```
+1. Generate a [Personal access token (classic)](https://github.com/settings/tokens).
+2. **Required Scopes**: Grant the `user` and `repo` scopes.
+3. Copy the token and keep it handy.
+
+## 🤝 Contribute
+
+Read the [Developer Guide](https://github.com/pythonpe/edit-python.pe/blob/main/CONTRIBUTING.md) to learn how to set up the development environment, run tests, and contribute translations.
+
+## ✨ Contributors
+
+A huge thanks to all the [individuals who have contributed](https://github.com/pythonpe/edit-python.pe/graphs/contributors?all=1) to this project.
 
-## Contribute
+## 📜 License
 
-Read the [Developer
-Guide](https://github.com/pythonpe/edit-python.pe/blob/main/CONTRIBUTING.md)
+This project is open-sourced software licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). Copyright 2024 Python Perú. See the [LICENSE](LICENSE) file for more details.