Skip to content

/languages directory

The /languages directory is mapped to /wp-content/languages. /languages is found in the root of an application’s wpcomvip GitHub repository and is intended for *.po and *.mo language translation files.

WordPress core translations

Adding language translations for WordPress core allows users to localize their WordPress Admin dashboard experience.

If an application’s repository has existing translation files (e.g., it_IT.*) with custom translation, those files should be backed up before following the steps below and overwriting them. The custom translations can later be backported into the updated {locale}.po and used to regenerate {locale}.mo.

In this example, Italian translation files for WordPress core are added:

  1. Clone the application’s wpcomvip GitHub repository to a local machine: 
    git clone git@github.com:wpcomvip/REPO_NAME.git
  2. Create a new working branch.
  3. Visit the Italian translation of WordPress.org (it.wordpress.org).
  4. Select “Get WordPress” (“Scarica WordPress“) button, then select the button on the next screen to download a copy of WordPress.
  5. Expand the archived file.
  6. Copy the language files found in the /wp-content/languages directory from the downloaded copy of WordPress into the /languages directory of the checked out branch.
  7. Commit, push up, and deploy the changes.

Plugin and theme translations

Internationalized plugins expect to find language translation files located in languages/plugins/, and internationalized themes expect to find language translation files located in languages/themes/.

The naming convention of language translation files for plugins and themes follow the pattern:

  • Plugins: plugin-name-{locale}.mo
    Example: languages/plugins/wp-parsely-ca_ES.mo
  • Themes: theme-name-{locale}.mo
    Example: languages/themes/twentytwentyone-en_GB.mo

Language translation plugins

Some language translation plugins expect that translation files can be written to a site’s uploads/ directory. Because the VIP File System is read-only, this will not work as expected.

To resolve this issue, language files can be added to /languages in a site’s wpcomvip GitHub directory instead:

  1. Clone the application’s wpcomvip GitHub repository to a local machine: 
    git clone git@github.com:wpcomvip/REPO_NAME.git
  2. Create a new working branch.
  3. Create a VIP Local Development Environment, or other preferred local development application.
  4. Enable the language translation plugin on the local development environment.
  5. Copy the language files generated by the plugin from local environment’s /wp-content/languages directory into the /languages directory of the checked out branch.
  6. Commit, push up, and deploy the changes.

Last updated: January 23, 2024

Relevant to

  • WordPress