Refactor Lang package to adapter-based architecture with FileAdapter, DeepL, and Google Translate support

[armanist]

Summary

Refactor the Lang package to support an adapter-based architecture instead of only the current built-in file translation flow.

The existing implementation should become a FileAdapter, and the package should add first-party support for DeepL and Google Translate adapters.

Why

Right now the Lang package is tightly coupled to local PHP translation files loaded from the application and module resource directories.

Other Quantum packages already follow an adapter/factory pattern (Cache, Mailer, Storage, etc.), so Lang is a good candidate to align with the broader framework design style.

This also opens the door for external translation providers without hardcoding vendor-specific logic directly into the current translator flow.

Proposed Changes

1. Introduce adapter-based Lang architecture

• Add a LangAdapterInterface
• Refactor the current file-based translation behavior into a dedicated FileAdapter
• Keep the existing public Lang surface intact where possible

2. Preserve current behavior through FileAdapter

• The current local translation loading from:
  • shared/resources/lang/...
  • modules/<module>/resources/lang/...
• should continue to work through the new FileAdapter
• Existing apps should not need to change behavior unless they opt into a different adapter

3. Add first-party remote adapters

Add support for:

• DeepLAdapter
• GoogleTranslateAdapter

These adapters should integrate cleanly with the Lang factory/config flow rather than bypassing it.

4. Add configurable caching for remote adapters

Remote translation providers must support caching so repeated requests do not re-hit the provider unnecessarily.

Requirements:

• reuse the framework’s existing cache patterns where practical
• make remote translation caching configurable
• include a stable cache key strategy based on at least:
  • provider/adapter name
  • source text
  • target locale
  • optional source locale
• return cached translations immediately when available
• on cache miss, fetch from provider and store the result

5. Add config support

Extend Lang config so applications can:

• select the active adapter
• configure provider credentials/settings
• configure remote translation caching behavior
• define failure/fallback behavior if needed

6. Define failure behavior clearly

Expected behavior should be explicit for cases like:

• unsupported adapter name
• missing provider credentials
• provider request failure
• cache unavailable or misconfigured

These should fail with clear LangException-level errors, and optional fallback behavior can be added only if intentionally designed.

Acceptance Criteria

• the current local translation flow continues to work via FileAdapter
• Lang adapter resolution is handled through the factory/config path
• DeepL and Google Translate adapters are supported
• remote adapters cache translation results
• repeated identical translation requests do not call the provider again unnecessarily
• unsupported adapter names throw a clear LangException
• tests cover:
  • FileAdapter behavior
  • adapter resolution
  • remote adapter caching behavior
• configuration/docs are updated to show the new Lang adapter structure

Notes

• Keep the current helper surface (t(), _t(), current_lang()) stable.
• Prefer consistency with existing framework package patterns over one-off Lang-specific wiring.
• The current implementation should be treated as the baseline FileAdapter, not discarded.