Common Laravel Package

Product Decisions This Supports

• Accelerated Localization Rollout: Enables rapid implementation of multilingual features (e.g., dynamic language switching, locale-aware UI) by providing standardized translation interfaces, reducing custom development time by 30–50% for i18n-heavy workflows.
• Global Market Expansion: Critical for products targeting non-English regions (e.g., Latin America, Asia) where pluralization, date/number formatting, and RTL (right-to-left) support are non-negotiable. Aligns with roadmaps for regionalized SaaS platforms or e-commerce with localized checkout flows.
• Tech Stack Modernization: Justifies upgrading to PHP 8.2–8.3 and Symfony 7.x, eliminating legacy dependencies and future-proofing the stack for Laravel 11+ or Symfony-heavy microservices.
• Build vs. Buy Decision: Validates adoption of a maintained, community-backed solution over in-house translation utilities, especially for teams lacking i18n expertise. Reduces technical debt by avoiding fragmented, ad-hoc implementations.
• API/Backend Consistency: Standardizes translation handling across API responses, validation messages, and CLI tools, ensuring uniformity in multilingual systems (e.g., headless CMS, multi-tenant SaaS).
• Compliance & Accessibility: Simplifies adherence to WCAG 2.1 (web accessibility) and localized legal requirements (e.g., GDPR data localization) by providing robust locale-aware formatting.

When to Consider This Package

Adopt when:

• Your primary use case is static file-based translations (e.g., JSON, YAML, PO/MO files) rather than real-time API translations (e.g., DeepL, Google Translate).
• You need pluralization support for languages like Arabic, Russian, or Chinese, where Laravel’s built-in trans() helper falls short.
• Your team is migrating to PHP 8.2–8.3 or Symfony 7.x and wants to avoid reinventing translation logic.
• You’re building a modular Laravel application (e.g., microservices, packages) where consistent translation interfaces are critical for interoperability.
• Localization is a core feature, not an afterthought (e.g., CMS, marketplace, or global enterprise software).
• You prioritize testability and want to decouple translation logic from business code (e.g., using dependency injection).

Look elsewhere if:

• Your translations are dynamically generated (e.g., AI-powered, user-uploaded content) and require real-time processing.
• You’re using PHP <8.2 or Symfony <6.4 and cannot upgrade due to legacy constraints.
• Your project relies on database-backed translations (e.g., PostgreSQL JSONB) with complex queries; this package is file-system/array-oriented.
• You need machine translation APIs (e.g., Google Cloud Translation) as a primary source—this package focuses on localization, not translation.
• Your team prefers JavaScript-first i18n (e.g., i18next, react-intl) and wants to avoid PHP duplication.
• You have highly specialized translation needs (e.g., medical, legal, or domain-specific terminology) that require custom parsing logic.

How to Pitch It (Stakeholders)

For Executives: *"This package is a force multiplier for our global expansion goals. By adopting php-translation/common, we can:

• Ship multilingual features 40% faster with standardized, tested translation logic—no more reinventing the wheel for every new locale.
• Future-proof our tech stack with PHP 8.3 and Symfony 7 support, aligning with Laravel’s long-term roadmap.
• Reduce localization bugs by handling edge cases (pluralization, RTL, date formats) automatically, cutting QA time for regional releases.
• Lower costs by avoiding custom i18n development, which often requires 2–3x more effort than leveraging maintained libraries.

For [Product X], this means faster time-to-market in [Target Region], fewer support tickets from localization issues, and a scalable foundation for future growth. The investment is minimal (a single Composer package), but the ROI is clear: higher quality, lower risk, and accelerated globalization."*

For Engineering: *"php-translation/common is the missing piece for Laravel’s i18n ecosystem. Here’s why it’s a no-brainer:

• Unified Interfaces: Standardizes translation loading, pluralization, and metadata across the app—no more inconsistent trans() hacks or magic strings.
• Symfony 7 + PHP 8.3 Ready: Drops legacy PHP and embraces modern tooling, so we’re not stuck maintaining old code.
• Lightweight but Powerful: Adds zero bloat—just the contracts, value objects, and utilities we need for translations, pluralization, and locale formatting.
• Laravel-Friendly: Integrates seamlessly with Laravel’s service container. Example:

  // Replace Laravel’s default translator with the package’s implementation
  $this->app->bind(
      TranslatorInterface::class,
      fn() => new \PhpTranslation\Common\Translator(
          new \PhpTranslation\Common\Loader\FileLoader(),
          new \PhpTranslation\Common\Cache\ArrayCache()
      )
  );
  

• Testability: Encourages clean architecture by decoupling translations from business logic—ideal for microservices or large codebases.
• Active Maintenance: Regular updates (e.g., Symfony 7 support in v3.3.0) show the package is not abandoned.

Trade-offs:

• Not a silver bullet for real-time translation APIs (use spatie/laravel-translation-manager or a dedicated API instead).
• Requires PHP 8.2+—if you’re stuck on PHP 8.0, this isn’t an option.

Recommendation: Start with a pilot (e.g., validation messages or API responses) before full adoption. The risk is low, and the upside is consistency, speed, and scalability for i18n."*

For Design/UX: *"This package ensures our translations are accurate and culturally appropriate, which is critical for:

• Pluralization: Correctly handling phrases like “You have {count} item(s)” in Arabic (which has 6 plural forms) or Russian (3 forms).
• Date/Number Formatting: Displaying dates as “15/05/2024” in the UK vs. “05/15/2024” in the US without manual overrides.
• RTL Support: Properly rendering Arabic/Hebrew text in web and email templates.

Action Item: Work with engineering to define locale-specific UX requirements (e.g., currency symbols, address formats) and validate the package’s formatting rules against our design system."*