Laravel Localization

Intelligent Laravel localization setup with server-side translations, automatic language detection, and SEO optimization. Designed for AI assistants to analyze and adapt to any project structure.

Features

• ✅ Server-side translations - Better SEO than client-side approaches
• ✅ Automatic language detection - Detects user's browser language preferences
• ✅ SEO-friendly URLs - Language-specific URLs with proper hreflang tags
• ✅ TypeScript support - Fully typed translation hooks
• ✅ SSR compatible - Works with Inertia.js SSR
• ✅ Intelligent setup - AI-guided installation that adapts to project patterns

Supported Languages

• pt (Portuguese) - Default language
• en (English)
• es (Spanish)

Installation

For Users (with AI Assistant)

Ask your AI assistant to set up localization by saying:

"Set up Laravel localization for my project using the laravel-localization package"

The AI will:

1. Analyze your project structure and naming conventions
2. Adapt the files to match your existing patterns
3. Install everything correctly in the right locations
4. Configure Laravel with proper settings

Note: Routes and examples are not automatically created. You must explicitly request them if needed.

Optional: Home Page Setup

If you want a basic home page example to get started, you can request:

"Set up Laravel localization with a home page example"

This will additionally create:

• A localized home route
• Basic translation files for the home page
• A simple home page component example

For AI Assistants

IMPORTANT: Read laravel-localization.md before proceeding. It contains essential instructions for:

• Project structure analysis
• File naming adaptation
• Import path configuration
• Compatibility verification

Manual Installation

# 1. Get the files
git clone https://github.com/weristwiegott/laravel-localization.git
cp -r laravel-localization your-project/
cd your-project

# 2. Follow laravel-localization.md for proper installation

What Makes This Different

Intelligent Adaptation

Unlike other packages, this one is designed to adapt to your project:

• Detects your naming conventions (kebab-case, camelCase, PascalCase)
• Follows your existing import patterns (@/ aliases, relative paths)
• Matches your component organization structure
• Respects your TypeScript/JavaScript preferences

AI-First Design

Built specifically for AI assistants to provide intelligent installation:

• Comprehensive analysis guidelines
• Pattern detection algorithms
• Adaptive file modification
• Smart conflict resolution

Files Included

• SetLocale.php → app/Http/Middleware/SetLocale.php
• Localized.php → app/Http/Routing/Localized.php
• use-translations.ts → resources/js/hooks/use-translations.ts
• LocalizedSeo.tsx → resources/js/components/seo/localized-seo.tsx
• laravel-localization.md → Complete setup guide for AI assistants (moved to docs/ during setup)

Usage

Creating Translation Files

Create translation files in lang/{language}/:

lang/pt/home.php:

<?php
return [
    'hero' => [
        'title' => 'Bem-vindo ao nosso site',
        'subtitle' => 'A melhor plataforma para você',
    ],
    'cta' => 'Começar agora',
];

Setting up Routes

Use the Localized::group() helper for automatic language routing:

use App\Http\Routing\Localized;

Localized::group(function () {
    Route::get('/', function () {
        return Inertia::render('HomePage', [
            'translations' => __('home'),
        ]);
    })->name('home');
});

Frontend Integration

Use the useTranslations() hook in your React components:

import { useTranslations } from '@/hooks/use-translations';
import { LocalizedSeo } from '@/components/seo/LocalizedSeo';

const HomePage = () => {
    const { t, locale } = useTranslations();

    return (
        <div>
            <LocalizedSeo
                locale={locale}
                title={t('hero.title')}
                description={t('hero.subtitle')}
            />

            <h1>{t('hero.title')}</h1>
            <p>{t('hero.subtitle')}</p>
            <button>{t('cta')}</button>
        </div>
    );
};

URL Structure

yoursite.com/           → Portuguese content (default)
yoursite.com/pt/        → Portuguese content
yoursite.com/en/        → English content
yoursite.com/es/        → Spanish content

Example AI Request

Users can simply ask their AI assistant:

"I need to add internationalization to my Laravel project. Set up localization for Portuguese, English, and Spanish with automatic language detection and SEO optimization."

The AI will handle the rest by following the laravel-localization.md.

Requirements

• PHP 8.2+
• Laravel 11+
• Inertia.js with React
• Node.js 18+

How It Works

1. Smart Project Analysis

AI analyzes your codebase to understand:

• File naming patterns (kebab-case vs camelCase)
• Import/export conventions
• Directory structures
• TypeScript vs JavaScript usage

2. Adaptive Installation

Files are moved and renamed to match your project:

• Move files to follow your directory structure
• Rename files to match your conventions during move
• Place components in your existing organization
• Configure routes using your existing patterns

3. Core Components

• SetLocale Middleware - Detects language from URL or browser preferences
• Localized Routing - Creates routes for all languages automatically
• Translation Hook - TypeScript-safe translation access in React
• SEO Component - Automatic hreflang tags for better SEO

Contributing

Feel free to submit issues and enhancement requests!

License

Open-sourced software licensed under the MIT license.