Update translation docs

[alganet]

The documents on translation were updated to feature symfony with
an array provider. Duplicated container notes were extracted to
a single configuration.md file.

An API for accessing the messages, so users don't have to copy
and paste them from the source or docs, was provided and
TemplateResolver was refactored to use it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.56%. Comparing base (570ba48) to head (0240807).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1675      +/-   ##
============================================
+ Coverage     99.53%   99.56%   +0.02%     
- Complexity      929      970      +41     
============================================
  Files           190      193       +3     
  Lines          2170     2280     +110     
============================================
+ Hits           2160     2270     +110     
  Misses           10       10              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a Template::from($class, $mode) static façade to make validator template lookup easier (supporting translation/migration scenarios), and updates translation/configuration documentation and examples accordingly.

Changes:

• Introduce Respect\Validation\Message\Template::from() for resolving a validator’s Template attribute by template id.
• Update translator feature test and translation docs to reference templates via Template::from(...) instead of hardcoded strings.
• Extract duplicated container notes into a new docs/configuration.md and update docs to link to it.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Message/Template.php	Adds Template::from() for reflective lookup of template attributes by id.
tests/unit/TemplateTest.php	New unit tests validating Template::from() behavior and error cases.
tests/feature/TranslatorTest.php	Updates translation resources to key off Template::from(...)->default and adds more template-based entries.
docs/migrating-from-v2-to-v3.md	Adds a migration note pointing readers to the updated translation docs.
docs/messages/translation.md	Reworks translation guide and includes Template::from(...)-based examples; links to configuration docs.
docs/messages/placeholder-conversion.md	Replaces duplicated container notes with a link to docs/configuration.md.
docs/configuration.md	New centralized container configuration documentation.
docs/case-sensitiveness.md	Updates example wording to reference v::after wrappers.

Comments suppressed due to low confidence (1)

tests/feature/TranslatorTest.php:44

• The translation resources are clearly Portuguese, but they’re registered under locale "en". This makes the example/test confusing and differs from the docs (which use pt_BR). Consider setting the Translator locale and the addResource locale to "pt_BR" to match the actual translations.

        'and' => 'e',
    ],
    'en',
);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[henriquemoody]

I can't see the reason why this method needs to exist. Can you elaborate on your reasoning?

[alganet]

It provides an API for getting the instance decoupled from the ContainterRegistry. It uses the container inside, but the user doesn't need to know about it. It's good for those scenarios (when knowledge of the container is not needed).

For example, if the user wants to reuse existing templates like this: v::templated(TemplateRegistry::getInstance()->get(IntVal::class), v::callback(... or in the assert replacements.

[alganet]

In fact, I still prefer having a Template::from for those kinds of scenarios. Can I move it back to the Template class just as a façade for the TemplateRegistry implementation?

[henriquemoody]

If that's the use case, I prefer Template::from as well. But then, I don't see a reason to have the TemplateRegistry.

I also think that if we want to do things like this v::templated(TemplateRegistry::getInstance()->get(IntVal::class), v::callback(..., we should provide a cleaner API for it, but I'm not sure I want to go there, if I'm honest.

I would keep the TemplateRegistry, as the in-memory caching layer is useful, but I would remove the getInstance() method. I think we should keep the cases in which we use the ContainterRegistry as minimum. When I created it, my goal was to enable it to be used just because we have a __callStatic() in the ValidatorBuilder, we should favor dependency injection in other parts of the library, IMO.

[alganet]

The use case is:

Q: As a user, how do I get a template for a given validator programaticallly?

It's a reasonable thing to ask. The answer is going to be something like this:

$container = ContainerRegistry::getContainer();
$templateRegistry = $container->get(TemplateRegistry::class);
$template = $templateRegistry->get(IntVal::class);

I think that answer sucks.

This answer would be better:

$template = Template::from(IntVal::class);

There's nothing preventing us from using all the cool tricks inside (a global registry, clean dependencies injected, etc). It doesn't prevent the user from providing his own TemplateRegistry (injecting dependencies), it just makes it easier to access the default one.

We never actually need the syntatic sugar, ever, right? The user can always deal with the raw building blocks directly. However, it's nice to have them.

[henriquemoody]

Q: As a user, how do I get a template for a given validator programmatically?

I think different use cases might call different solutions.

As an user, I want to have access to all the translations from Validation so I can translate them.

It's much easier if we provide them with a collection of messages we already have. It's static, there's no need for the user to get them dynamically for that scenario. But if that's the case, the TemplateRegistry works great, even better than the Template::from(), IMO.

As an user, I want to set the template of my custom validator as an existing validator.

That calls for something dynamic, but to me, something like v::templated(Template::from(IntVal::class)->default, v::callback(... sucks. If we want to provide the users with something like that, we could create a validator that does that, and then uses the TemplateRegistry/Factory as a dependency.

[alganet]

I removed the getInstance().

IMHO, our docs now are worse than the initial version I presented. We could totally have both (a beginner introduction with easier APIs and a more advanced section with TemplateRegistry).

In the end, I think we're shifting the complexity to the users. Look at how many distractions there are in the task of setting up translations. Façades like Template::from easy that burden while not invalidating under-the-hood implementations like TemplateRegistry.

[henriquemoody]

We could have Template::from() using TemplateRegistry via ContainerRegistry, I'd be fine with that as well, but I don't think need the TemplateRegistry::getInstance()

[alganet]

That is precisely what I was suggesting here 😆

alganet said: In fact, I still prefer having a Template::from for those kinds of scenarios. Can I move it back to the Template class just as a façade for the TemplateRegistry implementation?

[henriquemoody]

Dude, I'm so sorry... You said exactly that 😕

[henriquemoody]

If you want to recreated Template::from(), by all means! The PR is good for merge anyways.