PHP localization arrays

AI translation for PHP localization files with Lingo.dev CLI

What are PHP localization arrays?

PHP localization files use PHP array syntax to store translation strings. They are commonly used in PHP frameworks like Laravel for managing multi-language applications.

For example:

<?php

return [
    'Hello, world!',
    'Welcome to MyApp',

    'welcome_message' => 'Welcome!',
    'error_text'      => 'Something went wrong',

    'navigation' => [
        'home'    => 'Home',
        'about'   => 'About',
        'contact' => 'Contact',
    ],
];

What is Lingo.dev CLI?

Lingo.dev CLI is a free, open-source CLI for translating apps and content with AI. It's designed to replace traditional translation management software while integrating with existing pipelines.

To learn more, see Overview.

About this guide

This guide explains how to translate PHP localization files with Lingo.dev CLI.

You'll learn how to:

  • Create a project from scratch
  • Configure a translation pipeline
  • Generate translations with AI

Prerequisites

To use Lingo.dev CLI, ensure that Node.js v18+ is installed:

❯ node -v
v22.17.0

Step 1. Set up a project

In your project's directory, create an i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

This file defines the behavior of the translation pipeline, including what languages to translate between and where the localizable content exists on the file system.

To learn more about the available properties, see i18n.json.

Step 2. Configure the source locale

The source locale is the original language and region that your content was written in. To configure the source locale, set the locale.source property in the i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

The source locale must be provided as a BCP 47 language tag.

For the complete list of the locale codes that Lingo.dev CLI supports, see Supported locale codes.

Step 3. Configure the target locales

The target locales are the languages and regions you want to translate your content into. To configure the target locales, set the locale.targets property in the i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Step 4. Create the source content

If you haven't already, create one or more PHP localization files that contain the content to be translated. These files must be located at a path that includes the source locale somewhere in the path (e.g., as a directory name like en/ or as part of the filename like messages.en.php).

Step 5. Create a bucket

  1. In the i18n.json file, add a "php" object to the buckets object:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {}
  }
}

  2. In the "php" object, define an array of one or more include patterns:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {
      "include": ["./[locale]/example.php"]
    }
  }
}

    These patterns define which files to translate.

    The patterns themselves:

    • must contain [locale] as a placeholder for the configured locale
    • can point to file paths (e.g., "[locale]/messages.php")
    • can use asterisks as wildcard placeholders (e.g., "[locale]/*.php")

    Recursive glob patterns (e.g., **/*.php) are not supported.

Step 6. Configure an LLM

Lingo.dev CLI uses large language models (LLMs) to translate content with AI. To use one of these models, you need an API key from a supported provider.

To get up and running as quickly as possible, we recommend using Lingo.dev Engine — our own, hosted platform that offers 10,000 tokens of free, monthly usage:

  1. Sign up for a Lingo.dev account.

  2. Run the following command:

    npx lingo.dev@latest login

    This will open your default browser and ask you to authenticte.

  3. Follow the prompts.

Step 7. Generate the translations

In the directory that contains the i18n.json file, run the following command:

npx lingo.dev@latest run

This command:

  1. Reads the i18n.json file.
  2. Finds the files that need to be translated.
  3. Extracts the translatable content from the files.
  4. Uses the configured LLM to translate the extracted content.
  5. Writes the translated content back to the file system.

The first time translations are generated, an i18n.lock file is created. This file keeps track of what content has been translated, preventing unnecessary retranslations on subsequent runs.

Example

en/example.php

<?php

return [
    'Hello, world!',
    'Welcome to MyApp',

    "It's \"simple\" with a backslash \\ and newline\nAll text here",

    'welcome_message' => 'Welcome!',
    'error_text'      => 'Something went wrong',

    'navigation' => [
        'home'    => 'Home',
        'about'   => 'About',
        'contact' => 'Contact',
    ],

    'forms' => [
        'login' => [
            'username_label' => 'Username',
            'password_label' => 'Password',
            'submit_button'  => 'Sign In',
        ],
    ],

    'mixed_content' => [
        'title'        => 'Settings',
        'count'        => 42,
        'enabled'      => true,
        'nothing_here' => null,
        'description'  => 'App settings and preferences',
    ],
];

es/example.php

<?php

return [
    '¡Hola, mundo!',
    'Bienvenido a MyApp',

    "Es \"simple\" con una barra invertida \\ y salto de línea\nTodo el texto aquí",

    'welcome_message' => '¡Bienvenido!',
    'error_text'      => 'Algo salió mal',

    'navigation' => [
        'home'    => 'Inicio',
        'about'   => 'Acerca de',
        'contact' => 'Contacto',
    ],

    'forms' => [
        'login' => [
            'username_label' => 'Nombre de usuario',
            'password_label' => 'Contraseña',
            'submit_button'  => 'Iniciar sesión',
        ],
    ],

    'mixed_content' => [
        'title'        => 'Configuración',
        'count'        => 42,
        'enabled'      => true,
        'nothing_here' => null,
        'description'  => 'Configuración y preferencias de la aplicación',
    ],
];

i18n.json

{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {
      "include": ["./[locale]/example.php"]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}

i18n.lock

version: 1
checksums:
  0ee8d6907f60fa2cc288cc0503ecbba1:
    "0": 0468579ef2fbc83c9d520c2f2f1c5059
    "1": d1c3a9f35e377554a4ccaa467ca26614
    "2": 769caedbdc5246bb9fee615739534bbd
    3/welcome_message: 8778dc41547a2778d0f9482da989fc00
    4/error_text: a3cd2f01c073f1f5ff436d4b132d39cf
    5/navigation/home: 104a3db3b671c04e167eafbe21e57881
    5/navigation/about: 944521eeeed2511833d2299931273c71
    5/navigation/contact: 9afa39bc47019ee6dec6c74b6273967c
    6/forms/login/username_label: 2ee65bc2dd2f12cf2672f95b2a054bf8
    6/forms/login/password_label: 223a61cf906ab9c40d22612c588dff48
    6/forms/login/submit_button: ec7b8f314fe9bc6591006707484ede61
    7/mixed_content/title: 8df6777277469c1fd88cc18dde2f1cc3
    7/mixed_content/description: 063afcd2ea84a82a1acc8f5c9fd8e42f