LW Translate

Manage WordPress translations from community repositories.

Overview

Installation

composer require lwplugins/lw-translate

Or upload the lw-translate folder to /wp-content/plugins/ and activate through the Plugins menu.

Requirements

• PHP 8.1+
• WordPress 6.0+

Features

• Browse available translations for installed plugins and themes
• One-click install and update translations
• Formal and informal tone support (e.g., Hungarian: “magazo” vs “tegezo”)
• SHA-based update detection (no unnecessary downloads)
• WP_List_Table interface with search, sort, and filter
• Bulk install/update/delete actions
• Smart caching for GitHub API calls
• WP_Filesystem for safe file operations

How It Works

1. The plugin checks the community translation repository on GitHub
2. It compares available translations with your installed plugins/themes
3. Shows which translations are available, installed, or need updating
4. You can install or update translations with a single click

Translation Repository

LW Translate uses the hellowpio/wordpress-translations  GitHub repository which contains 393+ plugin and 9 theme translations.

Admin Pages

The plugin adds two pages under the LW Plugins menu:

1. Translations (LW Plugins > Translate)

The main page with a WP_List_Table showing all available translations.

Toolbar:

• Displays the current tone (Formal/Informal) and locale (e.g. hu_HU)
• Refresh Cache button to force-reload repository data from GitHub

Table columns:

View filters (above the table):

• All - Every translation available for your installed plugins/themes
• Plugins - Plugin translations only
• Themes - Theme translations only
• Updates Available - Translations where the remote version differs from local
• Not Installed - Translations available but not yet installed locally

Search: Use the search box to filter by plugin/theme name or slug.

Sorting: Click column headers (Name, Type, Status, Local Date) to sort.

Bulk actions:

1. Select items with checkboxes
2. Choose “Install/Update Selected” or “Delete Selected” from the dropdown
3. Click “Apply”

2. Translate Settings (LW Plugins > Translate Settings)

Settings page with the following options:

How It Works (Technical Details)

Translation Discovery

1. The plugin fetches the full file tree from the GitHub repository using the Trees API 
2. It parses the tree for files matching the pattern: {tone}/{plugins|themes}/{locale}/{slug}/
3. It cross-references this with your installed plugins (get_plugins()) and themes (wp_get_themes())
4. Only translations for installed items are shown

Update Detection (SHA Comparison)

The plugin uses git blob SHA hashes to detect changes:

• Remote SHA: Provided by the GitHub Trees API for each file
• Local SHA: Calculated from the local .mo file content using the same algorithm: sha1("blob " + filesize + "\0" + content)
• If SHAs match, the translation is up to date
• If they differ, an update is available
• If no local file exists, it shows as not installed

This approach avoids unnecessary downloads - only genuinely changed files trigger update notifications.

File Installation

When you click Install or Update:

1. The plugin downloads all translation files for that slug (.mo, .po, .l10n.php, .json)
2. Files are saved via WP_Filesystem to the standard WordPress language directory:
   • Plugins: WP_LANG_DIR/plugins/{slug}-{locale}.mo
   • Themes: WP_LANG_DIR/themes/{slug}-{locale}.mo
3. The comparison cache is cleared so the table reflects the new state

Repository Structure

The plugin expects this directory structure in the GitHub repository:

formal/
  plugins/
    hu_HU/
      akismet/
        akismet-hu_HU.mo
        akismet-hu_HU.po
      woocommerce/
        woocommerce-hu_HU.mo
        ...
  themes/
    hu_HU/
      flavor/
        flavor-hu_HU.mo
        ...
informal/
  plugins/
    hu_HU/
      ...

Caching

Cache is automatically cleared when:

• A translation is installed, updated, or deleted
• You click the “Refresh Cache” button
• The tree cache TTL expires naturally

Cache is also cleared when you change tone or locale in settings (via the comparison transient key which includes both values).

Settings

Configure under LW Plugins > Translate Settings for locale and tone preferences. Manage translations under LW Plugins > Translations.

WP-CLI Commands

# List available translations
wp lw-translate list
 
# Install a translation
wp lw-translate install <slug>
 
# Delete a translation
wp lw-translate delete <slug>
 
# Refresh translation cache
wp lw-translate refresh
 
# View or change settings
wp lw-translate settings

AI Abilities

When used with LW Site Manager, the following abilities are available for AI agents. All abilities are registered under the translate category and require manage_options capability. Abilities are only registered when LW Site Manager is active - the integration is a no-op otherwise.

lw-translate/list-translations (readonly)

Returns a list of installed translations and their current update status, comparing local files against the remote community repository.

Input:

Output:

{
  "success": true,
  "translations": [
    {
      "slug": "woocommerce",
      "name": "WooCommerce",
      "type": "plugin",
      "status": "update",
      "file_count": 3,
      "local_date": "2024-01-15 10:30+0000"
    }
  ],
  "total": 1
}

Status values:

lw-translate/get-options (readonly)

Returns the current LW Translate plugin settings.

Input: none required

Output:

{
  "success": true,
  "options": {
    "locale": "hu_HU",
    "tone": "formal",
    "cache_ttl": 43200
  }
}

lw-translate/install-translation (write)

Downloads and installs translation files for a specific plugin or theme from the remote community repository. Also serves as an update operation when a newer version is available.

Input:

Output:

{
  "success": true,
  "message": "Translation installed for plugin woocommerce."
}

lw-translate/update-translations (write)

Scans all installed plugins and themes, then updates every translation that has a newer version available in the remote repository.

Input: none required

Output:

{
  "success": true,
  "updated": ["plugin:woocommerce", "theme:storefront"],
  "failed": [],
  "total": 2
}

Failed item shape:

{
  "slug": "some-plugin",
  "type": "plugin",
  "message": "No translation files found for this item."
}

Notes:

• The translation source is the hellowpio/wordpress-translations  community repository on GitHub.
• Locale and tone are read from the active LW Translate settings at the time of each ability execution.
• After a successful install or update, the local comparison cache is cleared so subsequent list-translations calls reflect the new state.

Troubleshooting

No Translations Appear

• Check that you have plugins/themes installed that exist in the repository
• Click “Refresh Cache” to force a fresh API call
• Verify your locale setting matches the repository structure (e.g. hu_HU)

GitHub API Rate Limit

The GitHub API allows 60 requests/hour for unauthenticated requests. The plugin caches aggressively to stay well within this limit. If you hit the limit, wait an hour or increase the Cache TTL.

Translations Not Loading in WordPress

• Verify the .mo files are in the correct directory (WP_LANG_DIR/plugins/ or WP_LANG_DIR/themes/)
• Check that your WordPress site locale matches the translation locale (Settings > General > Site Language)
• Some plugins load translations from their own directory - these may not pick up files from WP_LANG_DIR

Permission Errors During Install

The plugin uses WP_Filesystem for file operations. If your server requires FTP credentials, WordPress will prompt for them. Ensure WP_LANG_DIR is writable by the web server.

Uninstall

When you delete the plugin through WordPress:

• The lw_translate_options option is removed
• All lw_translate_tree_cache and lw_translate_compare_* transients are cleaned up
• Installed translation files are NOT removed (they remain in WP_LANG_DIR)

FAQ

Which translation repository does this use?

The plugin uses the hellowpio/wordpress-translations  GitHub repository which contains 393+ plugin and 9 theme translations.

What is the difference between formal and informal tone?

Some translation repositories provide both formal and informal variants. Formal uses polite forms while informal uses familiar forms (e.g., in Hungarian: “magazo” vs. “tegezo”).

How does update detection work?

The plugin calculates git blob SHA hashes of your local .mo files and compares them with the remote repository. Only genuinely changed files trigger an update notification.