Laravel Translatable Laravel Package

Product Decisions This Supports

• Multilingual Content Strategy: Enables seamless support for localized content (e.g., global SaaS platforms, e-commerce, or CMS-driven applications) without requiring complex database schemas or third-party services.
• Roadmap for Scalable Localization: Accelerates development timelines for features like:
  • Dynamic language switching for users.
  • Region-specific content delivery (e.g., legal disclaimers, product descriptions).
  • SEO optimization with locale-aware metadata.
• Build vs. Buy Decision: Avoids reinventing translation storage/management logic, reducing technical debt compared to custom solutions. MIT license ensures compliance for open-source or proprietary projects.
• Use Cases:
  • CMS/Content Platforms: Store blog posts, product descriptions, or marketing copy in multiple languages within a single table.
  • Marketplaces: Localize product titles, categories, or vendor messages without duplicating tables.
  • Internal Tools: Support multilingual workflows (e.g., customer support tickets, documentation) for global teams.
  • Legacy System Modernization: Retrofit existing Eloquent models with translation support without schema migrations.

When to Consider This Package

• Adopt When:

  • Your application requires simple, JSON-based translation storage (no need for separate tables or complex joins).
  • You’re using Laravel/Eloquent and want to leverage native query capabilities (e.g., whereJsonContainsLocale).
  • Your team prioritizes developer velocity over fine-grained control (e.g., no need for translation caching layers or event-driven workflows).
  • You need basic fallback logic (e.g., default to English if a translation is missing) without external dependencies.
  • Your data model fits single-table inheritance for translations (e.g., no hierarchical or polymorphic relationships).

• Look Elsewhere If:

  • You need advanced translation workflows (e.g., approvals, versioning, or collaborative editing) → Consider Crowdin API, Transifex, or POEditor.
  • Your database doesn’t support JSON columns (e.g., legacy MySQL <5.7) → Use a package like afzan19/DB-Fields-Translations or normalize translations into separate tables.
  • You require performance-critical queries on translations → Denormalized JSON may slow down complex searches; consider a dedicated translation table with indexes.
  • Your application needs machine translation integration (e.g., auto-translate missing keys) → Combine with a service like Google Translate API via the missingKeyCallback.
  • You’re building a highly scalable system with millions of translations → Evaluate sharding or a dedicated translation database.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us ship multilingual features faster and cheaper by eliminating the need for custom translation infrastructure. For example, we can launch a global version of [Product X] in weeks instead of months by:

• Reducing dev time: No need to design/implement a translation database schema or integrate third-party APIs upfront.
• Lowering costs: Avoids per-translation fees from services like Crowdin or DeepL for basic use cases.
• Scaling effortlessly: JSON storage handles thousands of translations without performance hits, and we can always optimize later if needed. Think of it like adding ‘copy-paste for languages’—developers can mark any field as translatable in minutes, and we get localization without the complexity."

Risk Mitigation: "If our needs grow (e.g., we need translation approvals or machine learning), we can swap this out later. The MIT license gives us full control, and the package is battle-tested by 2,500+ GitHub stars."

For Engineering Teams:

*"spatie/laravel-translatable is a zero-config, JSON-based solution for Eloquent model translations that:

1. Simplifies the data model: Stores translations in a single JSON column (no joins, no extra tables).
2. Integrates natively with Laravel: Uses Eloquent accessors/mutators and supports Laravel’s query builder (e.g., whereJsonContainsLocale).
3. Reduces boilerplate: Add translations to any model with one trait and zero migrations (just annotate fields with #[Translatable]).
4. Supports edge cases:
   • Fallback locales (e.g., default to English if Spanish is missing).
   • Nested JSON translations (e.g., meta->description->en).
   • Custom logic for missing translations (e.g., log errors or fetch from an API).

Trade-offs:

• Not ideal for: Ultra-large datasets (JSON bloat) or complex workflows (e.g., translation memory).
• Alternatives: If you need separate tables or advanced features, we can evaluate afzan19/DB-Fields-Translations or a custom solution.

Proposal:

• Phase 1: Pilot with a non-critical model (e.g., blog posts or product descriptions).
• Phase 2: Extend to high-impact features (e.g., checkout flows, support tickets).
• Phase 3: Optimize if performance becomes an issue (e.g., add indexes or denormalize).

Example Workflow:

// Add to a model in 2 minutes:
#[Translatable('title', 'description')]
class BlogPost extends Model {
    use HasTranslations;
}

// Usage:
$post = new BlogPost();
$post->setTranslation('title', 'es', 'Título en Español');
$post->save();

// Query:
BlogPost::whereLocale('title', 'es')->get(); // All Spanish posts
```*

**Why This Over a Custom Solution?**
- **3x faster to implement**: No schema design, no ORM layer, no testing edge cases.
- **Maintainable**: Backed by Spatie (trusted Laravel package authors) with 2,500+ stars.
- **Future-proof**: Easy to replace or extend if needs change."*