Saltar al contenido principal

Laravel

El paquete neiderruiz/translate-projects-laravel extrae los textos de __(), trans() y @lang() a lang/<idioma base>.json, los traduce y escribe lang/en.json, lang/pt_BR.json, etc., que Laravel usa directamente.

Requisitos​

  • PHP 8.1 o superior y Laravel 10, 11, 12 o 13.
  • Un proyecto y un API token de Translate Projects. Mira Primeros pasos.

1. Instala el paquete​

Terminal
composer require neiderruiz/translate-projects-laravel
php artisan vendor:publish --tag=translate-config   # Opcional

2. Configura el .env​

.env
TRANSLATE_PROJECTS_API_KEY=tu_token
APP_LOCALE=es
TRANSLATE_PROJECTS_TARGET_LANGUAGES=en,pt-BR,fr
Clave en config/translate-projects.phpVariable de entornoPor defecto
api_keyTRANSLATE_PROJECTS_API_KEY—
api_urlTRANSLATE_PROJECTS_API_URLhttps://api.translateprojects.dev
default_localeTRANSLATE_PROJECTS_DEFAULT_LOCALE o APP_LOCALEen
target_languagesTRANSLATE_PROJECTS_TARGET_LANGUAGES (separados por comas)es,fr,de,it
scan_paths—app, resources, routes

default_locale debe coincidir con el idioma por defecto del proyecto en Translate Projects. Los códigos se pueden escribir como pt-BR, pt_BR o pt-br: el paquete usa pt-BR con la API y pt_BR en el nombre del archivo, como espera Laravel. Si usas php artisan config:cache, ejecuta php artisan config:clear después de cambiar el .env.

3. Marca tus textos​

routes/web.php
Route::get('/', fn () => __('Bienvenido a mi aplicación'));
resources/views/welcome.blade.php
<h1>{{ __('Hola mundo') }}</h1>
<p>{{ __('Bienvenido, :name', ['name' => $user->name]) }}</p>
<p>@lang('Este texto también se traduce')</p>

4. Extrae y traduce​

Terminal
php artisan translate:scan        # Extrae los textos a lang/es.json
php artisan translate             # Traduce a todos los idiomas destino
php artisan translate pt-BR       # Solo un idioma
php artisan translate --force     # Traduce aunque no haya cambios
  • translate:scan busca __('...'), trans('...'), trans_choice('...') y @lang('...') con un texto literal. Añade los textos nuevos a lang/<idioma base>.json y conserva los que ya estaban. Omite las claves de grupo (como auth.failed) y las de paquetes (pkg::archivo.clave).
  • translate sube los textos solo si cambiaron, espera al backend y escribe lang/<idioma>.json. Conserva las entradas que ya había en ese archivo, por ejemplo traducciones hechas a mano.

Archivos que genera​

lang/
├── es.json                    ← idioma base (generado por translate:scan)
├── en.json
├── pt_BR.json
├── fr.json
└── .translate-projects.json   ← caché

Caché y --force​

En lang/.translate-projects.json se guarda qué versión tiene cada idioma: una segunda ejecución sin cambios hace una sola petición y no traduce nada. Usa --force para traducir de nuevo aunque no haya cambios. Más detalles en Caché y errores.

Errores comunes​

El comando nunca deja un archivo a medias ni lo borra.

  • Falta TRANSLATE_PROJECTS_API_KEY: falla sin hacer peticiones. Si usas config:cache, ejecuta config:clear.
  • No se encontró o no es válido lang/es.json: todavía no extrajiste los textos: ejecuta php artisan translate:scan.
  • El idioma de origen no es el predeterminado o El idioma de destino no está activo en tu proyecto: revisa el idioma por defecto del proyecto o activa ese idioma en el panel.
  • Token inválido o error 4xx: muestra el código y el mensaje de la API y no toca los archivos.
  • Error 429, 5xx o de red: reintenta 3 veces; si sigue fallando, deja ese idioma como estaba y continúa con los demás.
  • Falta la key de IA (MISSING_API_KEY): escribe lo que llegó, avisa de cuántos textos faltan y los reintenta en la siguiente ejecución.
  • Placeholders: si la IA cambia un :placeholder, esa traducción se descarta y Laravel muestra el texto original.

Limitaciones​

  • Solo se traducen los archivos JSON (textos usados como clave). Los archivos de grupo lang/<idioma>/*.php no se suben.
  • No se detectan las claves dinámicas como __($variable).
Gratis

🚀 Automatiza tus traducciones gratis​

Translate Projects es gratuito. Creas tu proyecto, conectas la key de tu proveedor de IA y solo le pagas a él lo que gastes.

  • Sin planes ni tarjeta de crédito: Todas las funciones están disponibles desde el primer día.
  • Usa tu propia IA: Claude, OpenAI, DeepSeek o Gemini. Tu key se guarda cifrada.
  • Red de traducciones compartida: Si un texto ya fue traducido, lo recibes al instante sin gastar tu key.
  • Panel de administración: Revisa y edita todas tus traducciones desde un solo lugar.

Crear cuenta gratis →

Soporte

Estamos aquí para ayudarte​

Si tienes alguna pregunta, necesitas ayuda o quieres contribuir, no dudes en contactarme. Estoy a tu disposición para apoyarte en lo que necesites.

Apoya el Proyecto​

Si este proyecto te ha sido útil, te invito a invitarme un café. Tu apoyo me ayuda a seguir mejorando y creando contenido de valor. ¡Gracias por estar aquí! ☕

Buy me a coffee