Extending Custom Fields Translation

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

1. Add the filter code using one of the methods above
2. Clear any caches (if using caching plugins)
3. Navigate to the translation interface in your WordPress admin
4. Verify your custom fields appear in the translation options
5. Test translate a post/term with your custom fields
6. 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