WPML

BetterDocs – Reordering Docs Affects Categories in Secondary Languages

Published 2025-10-30 · Updated 2025-11-18
Status
Resolved by author
Resolved in
BetterDocs 4.2.3
Related plugin/theme
BetterDocs
Topic tags
Compatibility

Overview of the issue

When using BetterDocs with WPML, you might experience the following issue: reordering Docs via the BetterDocs drag-and-drop UI causes category assignments to become desynchronized in secondary languages. As a result, Docs may be incorrectly assigned to categories from other languages, and the new order may not be reflected across translations.

Workaround

Please, make sure of having a full site backup of your site before proceeding.


  • Open the …wp-content/plugins/betterdocs/includes/Core/PostType.php file.

  • Look for line 599.

  • Replace: 
    if ( update_term_meta( $term_id, '_docs_order', $docs_ordering_data ) ) {
    wp_send_json_success( __( 'Successfully updated.', 'betterdocs' ) );
}


  • With: 
    if ( update_term_meta( $term_id, '_docs_order', $docs_ordering_data ) ) {
    // WPML Integration: Sync taxonomies after order change
    if ( class_exists( 'SitePress' ) && class_exists( 'WPML_Term_Translation_Utils' ) ) {
        $docs_array = isset( $_POST['docs_ordering_data'] ) && is_array( $_POST['docs_ordering_data'] ) 
            ? array_map( 'intval', $_POST['docs_ordering_data'] )
            : explode( ',', $docs_ordering_data );
        $this->wpml_sync_posts_taxonomies( $docs_array );
    }
    
    wp_send_json_success( __( 'Successfully updated.', 'betterdocs' ) );
}


  • At the end of the same file, before the final } (around line 1130).

  • Add this helper function: 
    /**
 * WPML Integration: Sync post taxonomies across translations
 * @param array $post_ids Array of post IDs to sync
 */
private function wpml_sync_posts_taxonomies( $post_ids ) {
    global $sitepress;
    if ( ! $sitepress || empty( $post_ids ) ) return;

    $sync = new WPML_Term_Translation_Utils( $sitepress );
    
    foreach ( $post_ids as $post_id ) {
        $trid = $sitepress->get_element_trid( $post_id, 'post_docs' );
        if ( ! $trid ) continue;
        
        $translations = $sitepress->get_element_translations( $trid, 'post_docs' );
        $original_id = $post_id;
        
        foreach ( $translations as $translation ) {
            if ( isset( $translation->original ) && $translation->original == 1 ) {
                $original_id = $translation->element_id;
                break;
            }
        }
        
        foreach ( $sitepress->get_active_languages() as $lang => $details ) {
            $sync->sync_terms( $original_id, $lang );
        }
    }
}

All known issues →