Overview
The Polylang Automatic AI Translation plugin provides built-in support for translating custom fields from popular plugins like ACF, Yoast SEO, Rank Math, and others. However, for custom fields created with your own code or specialized plugins, you’ll need to extend the plugin’s functionality using provided filter hooks.
Why Custom Fields Need Manual Configuration
By design, the plugin only translates explicitly configured custom fields to prevent:
- Translation of sensitive data (API keys, configuration values)
- Breaking functionality that depends on specific field values
- Unwanted costs from translating non-textual content
Available Filter Hooks
The plugin provides two main filter hooks for extending custom field translation support:
1. Post Meta Fields Hook
Hook Name: pllat_available_post_meta_translation_fields
Purpose: Add custom fields for posts, pages, and custom post types
Usage:
add_filter('pllat_available_post_meta_translation_fields', function($fields) {
$fields[] = 'your_custom_field_key';
$fields[] = 'another_custom_field';
$fields[] = 'description_field';
return $fields;
});2. Term Meta Fields Hook
Hook Name: pllat_available_term_meta_translation_fields
Purpose: Add custom fields for categories, tags, and custom taxonomies
Usage:
add_filter('pllat_available_term_meta_translation_fields', function($fields) {
$fields[] = 'category_description';
$fields[] = 'term_subtitle';
$fields[] = 'custom_term_field';
return $fields;
});Implementation Methods
Method 1: Theme Functions File
Add the filter code to your active theme’s functions.php file:
// Add to wp-content/themes/your-theme/functions.php
add_filter('pllat_available_post_meta_translation_fields', function($fields) {
// Add your custom post meta fields
$custom_fields = [
'product_description',
'location_address',
'company_bio',
'custom_excerpt'
];
return array_merge($fields, $custom_fields);
});
add_filter('pllat_available_term_meta_translation_fields', function($fields) {
// Add your custom term meta fields
$custom_term_fields = [
'category_subtitle',
'term_description_extended',
'location_details'
];
return array_merge($fields, $custom_term_fields);
});Method 2: Custom Plugin
Create a small plugin to ensure the filters persist across theme changes:
<?php
/**
* Plugin Name: Custom Fields Translation Extension
* Description: Extends Polylang AI Translation to support custom fields
* Version: 1.0
*/
// Prevent direct access
if (!defined('ABSPATH')) {
exit;
}
class CustomFieldsTranslationExtension {
public function __construct() {
add_filter('pllat_available_post_meta_translation_fields', [$this, 'add_post_meta_fields']);
add_filter('pllat_available_term_meta_translation_fields', [$this, 'add_term_meta_fields']);
}
public function add_post_meta_fields($fields) {
$custom_fields = [
'your_custom_field_1',
'your_custom_field_2',
'product_specifications',
'location_description'
];
return array_merge($fields, $custom_fields);
}
public function add_term_meta_fields($fields) {
$custom_term_fields = [
'category_banner_text',
'term_seo_description',
'location_details'
];
return array_merge($fields, $custom_term_fields);
}
}
new CustomFieldsTranslationExtension();Identifying Your Custom Field Keys
To find the correct field keys for your custom fields:
Method 1: Database Inspection
-- For post meta fields
SELECT DISTINCT meta_key FROM wp_postmeta WHERE meta_key NOT LIKE '\_%' ORDER BY meta_key;
-- For term meta fields
SELECT DISTINCT meta_key FROM wp_termmeta WHERE meta_key NOT LIKE '\_%' ORDER BY meta_key;Method 2: WordPress Debug
Add this temporary code to see all meta fields for a specific post:
// Temporary debug code - remove after identifying fields
$post_id = 123; // Replace with your post ID
$meta = get_post_meta($post_id);
error_log(print_r($meta, true));Method 3: Code Review
Check your custom post type registration or meta box creation code for field names:
// Look for calls like:
add_meta_box('my_meta_box', 'Title', 'callback', 'post_type');
update_post_meta($post_id, 'field_name', $value);
get_post_meta($post_id, 'field_name', true);Best Practices
Field Selection Guidelines
- Include: Text fields, descriptions, titles, content meant for visitors
- Exclude: IDs, URLs, configuration values, serialized data, encoded content
Code Organization
add_filter('pllat_available_post_meta_translation_fields', function($fields) {
$custom_fields = [
// Product fields
'product_short_description',
'product_benefits',
// Location fields
'location_description',
'opening_hours_note',
// Event fields
'event_summary',
'speaker_bio'
];
return array_merge($fields, $custom_fields);
});Testing Your Implementation
- Add the filter code using one of the methods above
- Clear any caches (if using caching plugins)
- Navigate to the translation interface in your WordPress admin
- Verify your custom fields appear in the translation options
- Test translate a post/term with your custom fields
- Check the translated version to confirm fields were translated
Common Field Types Supported
The plugin can translate various custom field types:
- Text fields
- Textarea fields
- Rich text/WYSIWYG content
- Simple HTML content
- Plain text descriptions
Troubleshooting
Fields Not Appearing
- Verify the field key names are correct
- Check that the filter is properly hooked
- Ensure no PHP errors in your code
- Clear any caching
Fields Not Translating
- Confirm the field contains translatable text content
- Check that the field value is not empty
- Verify your OpenAI API key is working
- Review translation logs for errors
Performance Considerations
- Only add fields that actually need translation
- Avoid adding fields with large amounts of data
- Consider the cost implications of translating many fields