Add Spanish translation of the README documentation

[jlariza]

What type of PR is this? (check all applicable)

• Refactor
• Feature
• Bug Fix
• Optimization
• Documentation Update
• Other

Description

Summary

This PR introduces a full Spanish translation of the project's README documentation (README.es.rst), making the library accessible to Spanish-speaking developers. The translation covers the complete content of the existing README.rst, including all sections on installation, core concepts, API usage, matchers, callbacks, and advanced features.

No i18n framework or language-switching infrastructure was introduced — the Spanish documentation is provided as a standalone locale file following the .es.rst naming convention.

Changes

• Added README.es.rst: full Spanish translation of README.rst (1,560 lines)
• All narrative content, section headings, tables, and inline explanations translated to Spanish
• Code examples preserved exactly as in the original English version
• Code block comments translated where present within documentation snippets

Code Safety

No source code files were modified. The change is limited exclusively to the addition of README.es.rst. All 52 code blocks within the translated file retain their original Python syntax and logic, with only inline comments adapted to Spanish where applicable.

Testing

To validate this PR:

1. Open README.es.rst and verify it renders correctly as reStructuredText (e.g., via a local RST preview tool or sphinx-build)
2. Compare section structure against README.rst to confirm full coverage — no sections should be missing
3. Spot-check code examples to confirm they are identical to the originals (aside from translated inline comments)
4. Verify that deprecation tables, parameter tables, and directive blocks render properly

---

Claude Code was used in the coding process. Everything was reviewed and corrected by humans when necessary.

PR checklist

Before submitting this pull request, I have done the following:

• Read the contributing guidelines
• Ran tox and pre-commit checks locally
• Added my changes to the CHANGES file

Added/updated tests?

Current repository has 100% test coverage.

• Yes
• No, and this is why: it is a documentation update only.
• I need help with writing tests

[markstory]

Thank you for putting this together. I don't know how this documentation would be maintained long term as the maintainer team (me) is not fluent in Spanish, so the documentation will eventually become out of date.

[jlariza]

Thank you for putting this together. I don't know how this documentation would be maintained long term as the maintainer team (me) is not fluent in Spanish, so the documentation will eventually become out of date.

@markstory reviewing README.rst commit history; it seems that in the last 3 years less than 10 documentation related commits have been done; so I think that eventual situation would happen in a very long time.

Still, I could keep monitoring the documentation and updating the spanish version when it is required. WDYT?