📚 Complete Help Guide

Welcome to the comprehensive user guide for WP Content Sync & Translate. This plugin enables automatic content synchronization and AI-powered translation across multiple WordPress sites.

📖 Table of Contents

Overview & Introduction
Core Features
How It Works
Configuration Guide
Usage Guide
Per-Field Sync Control
Taxonomy Translation
Custom Post Types
Troubleshooting
Frequently Asked Questions
Developer Documentation
Support & Contact

💡 Quick Links:

New to this plugin? Start with Quick Installation Guide
Looking for specific features? Jump to Features Section
Having issues? Check Troubleshooting or FAQ

✨ Core Features

🔄 Real-Time Synchronization

Content syncs instantly when you publish or update posts. No delays, no manual triggers.

🌍 AI-Powered Translation

🎯 Granular Field Control

Choose exactly which fields to sync and translate for each post type.

🏷️ Dynamic Taxonomy Translation

Automatically translate categories, tags, and custom taxonomies.

🖼️ Media Sync

Featured images are downloaded and uploaded to target site automatically.

🔒 Enterprise Security

HMAC-SHA256 authentication with domain verification ensures secure communication.

📊 Comprehensive Logging

Track all sync operations with detailed logs on both Host and Target sites.

⚡ Zero Performance Impact

Sync happens asynchronously via REST API without slowing down your site.

Supported Languages

Language	Native Name	Code
French	Français	fr
Spanish	Español	es
Hindi	हिन्दी	hi
Gujarati	ગુજરાતી	gu
German	Deutsch	de
Italian	Italiano	it
Portuguese	Português	pt
Russian	Русский	ru
Chinese	中文	zh
Japanese	日本語	ja
Korean	한국어	ko
Arabic	العربية	ar
Turkish	Türkçe	tr
Polish	Polski	pl
Dutch	Nederlands	nl
Swedish	Svenska	sv
Norwegian	Norsk	no
Danish	Dansk	da
Finnish	Suomi	fi
Greek	Ελληνικά	el

🔧 How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│              HOST SITE (English)                         │
│  1. User publishes "Breaking News" post                 │
│  2. Plugin captures save_post hook                      │
│  3. Prepares data (title, content, categories, etc.)    │
│  4. Signs request with HMAC-SHA256                      │
│  5. Sends via REST API to Target Site(s)                │
└─────────────────────────────────────────────────────────┘
                         ↓ (REST API)
┌─────────────────────────────────────────────────────────┐
│              TARGET SITE (French)                        │
│  6. Receives and validates request                      │
│  7. Verifies HMAC signature                             │
│  8. Translates content via ChatGPT:                     │
│     "Breaking News" → "Nouvelles de Dernière Heure"     │
│  9. Translates categories: "Technology" → "Technologie" │
│ 10. Creates/updates post with translated content        │
│ 11. Syncs featured image and taxonomies                 │
│ 12. Post published in French! ✓                         │
└─────────────────────────────────────────────────────────┘

Step-by-Step Flow

Content Creation
User publishes or updates a post on the Host site.
Data Collection
Plugin gathers all configured fields (title, content, taxonomies, etc.).
Field Filtering
Only fields enabled in settings are included in sync.
Request Signing
Generates HMAC signature for security verification.
API Call
Sends data to each configured Target site via REST API.
Authentication
Target site verifies signature and domain.
Translation
Content is translated using ChatGPT API if translate is enabled.
Taxonomy Translation
Categories, tags, and custom taxonomies are translated.
Media Sync
Featured images are downloaded and uploaded to target media library.
Post Creation
New post is created (or existing post updated) with translated content.
Logging
Both sites log the operation for audit trail.
Success
Post is now live on Target site in the selected language.

💡 Pro Tip: All sync operations are logged. Check the "Sync Activity Logs" section at the bottom of the settings page to monitor all sync activities.

⚙️ Configuration Guide

Host Site Configuration

The Host site is where you create and manage content.

Step 1: Select Mode

Go to Settings → Content Sync & Translate
Under "Configuration Mode", select Host
Click Save Changes

Step 2: Add Target Sites

Click + Add Target Site button
Enter target site details:
- Target Site URL: Full URL (e.g., https://french.example.com)
- Target Site Key: Copy from target site settings
Click Save Changes
Repeat for additional target sites

Step 3: Configure Post Types

Click + Add Post Type
Select a post type from dropdown (Posts, News, etc.)
Fields will load automatically based on post type support
For each field, enable:
- Sync ✓ = Include this field in synchronization
- Translate ✓ = Translate this field on target
Use toggle button (▼) to expand/collapse field list
Use ↑↓ buttons to reorder post types
Use ✕ button to remove post type
Click Save Changes

Target Site Configuration

The Target site receives and translates content.

⚠️ CRITICAL: Permalinks MUST be enabled!
Go to Settings → Permalinks and select any option except "Plain".

Step 1: Select Mode

Go to Settings → Content Sync & Translate
Under "Configuration Mode", select Target
Click Save Changes

Step 2: Copy Authentication Key

In "Target Site Configuration" section
Click Copy button next to Authentication Key
Provide this key to Host site administrator
Paste it in Host site's "Target Site Key" field

Step 3: Configure Translation

Translation Language: Select target language (French, Spanish, etc.)
ChatGPT API Key: Enter your OpenAI API key
- Get from: https://platform.openai.com/api-keys
- Format: sk-proj-xxxxxxxxxxxxx
Click Save Changes

📖 Usage Guide

Creating and Syncing Posts

Create Post on Host Site
Go to Posts → Add New (or any configured post type)

Fill in:
- Title
- Content
- Excerpt (optional)
- Categories and Tags
- Featured Image
Publish Post
Click Publish button

Sync happens automatically within seconds
Verify on Target Site
Go to target site → Posts → All Posts

Translated post should appear with:
- Translated title
- Translated content
- Translated categories/tags
- Synced featured image

Updating Posts

Simply edit and update the post on Host site. Changes sync automatically to Target sites. The plugin uses post ID mapping to ensure the correct post is updated (not duplicated).

Deleting Posts

When you delete a post on Host site, the target site post is set to Draft status (soft delete). The post is preserved on Target but unpublished. You can manually delete it on Target if desired.

Scheduling Posts

Schedule a post on Host site, and when WordPress publishes it automatically, the plugin detects and syncs to Target sites. Translation happens at publish time.

✅ Best Practice: Always check the Sync Activity Logs after publishing to ensure successful sync.

🎯 Per-Field Sync Control

Control exactly which fields to sync and translate for each post type.

Field Types

Field Type	Can Sync	Can Translate	Examples
Text Fields	✓	✓	Title, Content, Excerpt
Taxonomy Fields	✓	✓	Categories, Tags, Custom Taxonomies
Media Fields	✓	—	Featured Image, Gallery
Custom Fields	✓	✓	ACF Fields, Meta Fields

Field Behavior Matrix

Sync	Translate	Result
✓	✓	Field is synced and translated
✓	✗	Field is synced without translation
✗	—	Field is not synced at all

Use Cases

Use Case 1: Multilingual Blog

Title:	Sync ✓	Translate ✓	(Readers see translated titles)
Content:	Sync ✓	Translate ✓	(Full content in target language)
Categories:	Sync ✓	Translate ✓	(Categories in target language)

Use Case 2: Technical Documentation

Title:	Sync ✓	Translate ✓	(Translated for readability)
Content:	Sync ✓	Translate ✗	(Keep technical terms as-is)
Categories:	Sync ✓	Translate ✗	(Standard category names)

🏷️ Taxonomy Translation

The plugin intelligently translates all taxonomy terms when enabled.

How It Works

Detection
Plugin automatically detects all taxonomies for each post type.
Translation
When translate is enabled, term names are sent to ChatGPT for translation.
Creation
If translated term doesn't exist on target, it's created automatically.
Assignment
Post is assigned to translated terms on target site.

Example Translation

Site	Title	Categories	Tags
Host (EN)	10 Best Smartphones in 2026	Technology, Reviews	smartphones, mobile, gadgets
Target (FR)	10 Meilleurs Smartphones en 2026	Technologie, Critiques	smartphones, mobile, gadgets

Term Matching Logic

The plugin prevents duplicate terms:

First Check: Searches for translated term by name
Second Check: Searches by slug if name not found
Create: Creates new term if it doesn't exist
Reuse: Uses existing term if already created

💡 Pro Tip: If you have custom taxonomies, they will be automatically detected and can be translated just like categories and tags.

📝 Custom Post Types

The plugin works with any public custom post type that has REST API support.

Requirements

Post type must be registered on both Host and Target sites
Post type must have 'public' => true
Post type must have 'show_in_rest' => true
Post type slug must be identical on both sites

Example: Registering a Custom Post Type

Add this code to your theme's functions.php on both sites:

// Register 'News' post type
function register_news_post_type() {
    register_post_type( 'news', array(
        'labels' => array(
            'name' => 'News',
            'singular_name' => 'News Item'
        ),
        'public' => true,
        'has_archive' => true,
        'supports' => array( 
            'title', 
            'editor', 
            'excerpt', 
            'thumbnail',
            'custom-fields'
        ),
        'taxonomies' => array( 'category', 'post_tag' ),
        'show_in_rest' => true, // REQUIRED for sync
    ));
}
add_action( 'init', 'register_news_post_type' );

Registering Custom Taxonomies

// Register custom taxonomy for News
function register_news_taxonomy() {
    register_taxonomy( 'news_type', array( 'news' ), array(
        'labels' => array(
            'name' => 'News Types',
            'singular_name' => 'News Type'
        ),
        'hierarchical' => true,
        'show_in_rest' => true, // REQUIRED for sync
    ));
}
add_action( 'init', 'register_news_taxonomy' );

⚠️ Important: After registering custom post types, go to Settings → Permalinks and click "Save Changes" to flush rewrite rules.

🔧 Troubleshooting

1. Sync Not Working

Symptoms:

Posts don't appear on target site after publishing.

Solutions:

✓ Check permalinks on target site (must not be "Plain")
✓ Verify target URL is correct in Host settings (include https://)
✓ Confirm authentication keys are correct (no extra spaces)
✓ Test REST API: Visit https://target-site.com/wp-json/
✓ Review Sync Activity Logs on both sites for error messages
✓ Ensure post type is registered on both sites with same slug
✓ Verify at least one field is enabled for sync in post type configuration
✓ Check if target site is accessible from host server (firewall/hosting restrictions)

2. Translation Not Working

Symptoms:

Content syncs but appears in original language, not translated.

Solutions:

✓ Verify ChatGPT API key is valid and properly formatted
✓ Check OpenAI account has available credits/billing set up
✓ Ensure "Translate" checkbox is enabled for fields in Host settings
✓ Test API key at OpenAI Platform
✓ Review target site logs for ChatGPT API errors
✓ Verify translation language is selected in Target settings
✓ Check if API rate limits are exceeded (OpenAI limits)

3. Categories/Tags Not Translating

Symptoms:

Taxonomies sync but keep original language.

Solutions:

✓ Enable "Translate" checkbox for Categories/Tags in Host settings
✓ Verify taxonomy is supported by the post type
✓ Check taxonomy is registered on target site
✓ Ensure "Sync" is also enabled for the taxonomy
✓ Review logs for taxonomy-specific errors

4. Featured Image Not Syncing

Symptoms:

Images don't appear on target site.

Solutions:

✓ Enable "Sync" for Featured Image in post type configuration
✓ Verify image URL is publicly accessible (not localhost)
✓ Check target site upload directory permissions (775 or 755)
✓ Ensure target server can download external images (allow_url_fopen enabled)
✓ Verify image file size is within WordPress/server limits
✓ Check if firewall/CDN is blocking image downloads

5. Authentication Errors

Symptoms:

"Authentication failed" or "Invalid signature" errors in logs.

Solutions:

✓ Re-copy authentication keys from target (avoid manual typing)
✓ Verify target URL exactly matches (including https:// and no trailing slash)
✓ Check server time is synchronized (important for HMAC signatures)
✓ Regenerate keys by re-saving Target site settings
✓ Confirm target site is reachable from host server
✓ Disable security plugins temporarily to test

6. Custom Post Type Not Appearing

Symptoms:

Custom post type not available in Host settings dropdown.

Solutions:

✓ Verify post type is registered with 'public' => true
✓ Ensure post type has 'show_in_rest' => true
✓ Check post type is not in excluded list (page, attachment, revision, nav_menu_item)
✓ Refresh/reload settings page after registering post type
✓ Flush permalinks: Settings → Permalinks → Save Changes

Debug Mode

Enable WordPress debug mode to see detailed error messages:

// Add to wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Logs will be written to: wp-content/debug.log

Checking Sync Logs

Go to Settings → Content Sync & Translate
Scroll to bottom of page
View Sync Activity Logs table
Look for errors, warnings, or failure status
Check timestamp to correlate with publish time

💡 Pro Tip: Always check logs on BOTH Host and Target sites to get complete picture of what happened during sync.

❓ Frequently Asked Questions

General Questions

Q: Does this work with WordPress Multisite?

A: Yes! Each site in a multisite network can be configured independently as Host or Target.

Q: Can I use one site as both Host and Target?

A: No. Each site must be either Host or Target, not both. However, you can create a chain (Site A → Site B → Site C) where Site B is Target for Site A and Host for Site C.

Q: How many target sites can I add?

A: Unlimited! Add as many target sites as needed. Content will be synced to all of them simultaneously.

Q: Does it work with custom post types?

A: Yes! Any public custom post type with REST API support will work. Common examples: WooCommerce Products, Events, Portfolio Items, etc.

Q: Can I sync WordPress Pages?

A: Pages are excluded by default to prevent syncing static pages. If you need to sync pages, you can enable them, but be cautious as system pages might get synced too.

Translation Questions

Q: Which translation service is used?

A: OpenAI's ChatGPT API (GPT-4 model). This provides high-quality, context-aware translations.

Q: How much does translation cost?

A: Based on OpenAI's pricing (as of 2026): approximately $0.01-0.03 per 1000 words. Costs vary based on content length and model used.

Q: Can I use a different translation service?

A: Currently only ChatGPT is supported. The plugin architecture is extensible, so additional services may be added in future versions.

Q: Does it preserve HTML formatting?

A: Yes! HTML structure, links, formatting, and WordPress blocks are preserved during translation.

Q: Can I manually edit translated content?

A: Yes! You can manually edit any translated post on the target site. However, if the Host post is updated, it will overwrite your changes.

Sync Questions

Q: Is sync real-time?

A: Yes! Posts sync immediately upon publish/update. Typically takes 2-10 seconds depending on content size and translation time.

Q: Does it use WordPress Cron?

A: No. Sync happens via REST API in real-time, not via scheduled cron jobs.

Q: What happens if target site is down?

A: The sync will fail and be logged on the Host site. You can manually trigger a re-sync by updating the post again once the Target is back online.

Q: Can I bulk sync existing posts?

A: Bulk sync is not available in v1.0.0. Currently, you need to update each post individually to trigger sync. Bulk sync is planned for a future release.

Q: Does it sync comments?

A: No, comments are not synced in v1.0.0. Comment synchronization is a planned future feature.

Security Questions

Q: How is data secured during sync?

A: HMAC-SHA256 signatures ensure request authenticity, domain verification prevents unauthorized access, and all communication happens over HTTPS.

Q: Do I need to open firewall ports?

A: No special ports needed. Standard HTTPS (port 443) is used for all communication.

Q: Can anyone sync to my target site?

A: No. Only sites with the correct authentication key can sync. Keys are unique and can be regenerated at any time.

Q: Are API keys stored securely?

A: Yes, in the WordPress database with the same security as other sensitive settings. Ensure your hosting environment is secure.

Technical Questions

Q: Does it affect site performance?

A: Minimal impact. Sync happens asynchronously via REST API. Host site publish process is delayed by 1-2 seconds for the API call.

Q: Will it slow down my publish process?

A: Slightly (1-2 seconds) for the API call initiation, but WordPress publish completes normally. Translation happens on the target side asynchronously.

Q: Does it work with page builders?

A: Yes! Works with Gutenberg (Block Editor), Elementor, Divi, WPBakery, and other popular page builders.

Q: Can I sync custom fields (ACF)?

A: Yes, if "Custom Fields" sync is enabled for the post type. ACF fields stored as post meta will be synced.

Q: What hosting is required?

A: Any standard WordPress hosting with REST API enabled. Shared hosting works fine as long as outbound HTTPS requests are allowed.

🛠️ Developer Documentation

Hooks & Filters

The plugin provides several hooks for customization.

Actions

// Before sync starts
do_action( 'wcst_before_sync', $post_id, $post, $target_sites );

// After successful sync
do_action( 'wcst_after_sync', $post_id, $post, $results );

// Before translation
do_action( 'wcst_before_translate', $text, $language );

// After translation
do_action( 'wcst_after_translate', $translated_text, $original_text, $language );

Filters

// Modify sync data before sending
apply_filters( 'wcst_sync_data', $data, $post_id );

// Modify translation before saving
apply_filters( 'wcst_translated_content', $translated, $original, $language );

// Modify target sites list
apply_filters( 'wcst_target_sites', $targets );

// Modify supported languages
apply_filters( 'wcst_supported_languages', $languages );

Custom Implementation Examples

Exclude Specific Categories from Sync

add_filter( 'wcst_sync_data', function( $data, $post_id ) {
    // Don't sync posts in "Draft" category
    $categories = wp_get_post_categories( $post_id, array( 'fields' => 'names' ) );
    if ( in_array( 'Draft', $categories ) ) {
        return false; // Abort sync
    }
    return $data;
}, 10, 2 );

Add Custom Meta Field to Sync

add_filter( 'wcst_sync_data', function( $data, $post_id ) {
    // Add custom field to sync data
    $data['custom_fields']['my_custom_field'] = get_post_meta( 
        $post_id, 
        'my_custom_field', 
        true 
    );
    return $data;
}, 10, 2 );

Log All Sync Operations

add_action( 'wcst_after_sync', function( $post_id, $post, $results ) {
    // Log to custom analytics service
    error_log( sprintf(
        'Synced post #%d (%s) to %d target sites',
        $post_id,
        $post->post_title,
        count( $results )
    ));
}, 10, 3 );

Modify Translation Before Saving

add_filter( 'wcst_translated_content', function( $translated, $original, $language ) {
    // Add custom footer to translated content
    $translated .= '<p><em>Translated to ' . $language . '</em></p>';
    return $translated;
}, 10, 3 );