Add WPML/Polylang support, related-articles fallback, and CPT/URL fixes

- Language_Handler: add get_current_language() and get_translated_term_id() for WPML and Polylang
- Display: include language slug in cache keys so multilingual sites don't share cached output
- Widgets: resolve stored term/product IDs to the current language before querying
- Related: fall back to sibling sections (same product, different section) when primary query returns nothing
- wzkb_get_kb_url(): prefer get_post_type_archive_link() over the manual slug construction
- CPT: pass suppress_filters => false to both get_posts() calls

Author: ajaydsouza

includes/class-cpt.php

@@ -371,10 +371,11 @@ public static function maybe_query_kb_article( $query ) {
 		// Check if there's a regular post with this slug first.
 		$regular_post = get_posts(
 			array(
-				'name'           => $post_name,
-				'post_type'      => 'post',
-				'post_status'    => 'publish',
-				'posts_per_page' => 1,
+				'name'             => $post_name,
+				'post_type'        => 'post',
+				'post_status'      => 'publish',
+				'posts_per_page'   => 1,
+				'suppress_filters' => false,
 			)
 		);
 
@@ -386,10 +387,11 @@ public static function maybe_query_kb_article( $query ) {
 		// No regular post found, check if there's a KB article with this slug.
 		$kb_post = get_posts(
 			array(
-				'name'           => $post_name,
-				'post_type'      => 'wz_knowledgebase',
-				'post_status'    => 'publish',
-				'posts_per_page' => 1,
+				'name'             => $post_name,
+				'post_type'        => 'wz_knowledgebase',
+				'post_status'      => 'publish',
+				'posts_per_page'   => 1,
+				'suppress_filters' => false,
 			)
 		);
 

includes/frontend/class-display.php

@@ -7,6 +7,7 @@
 
 namespace WebberZone\Knowledge_Base\Frontend;
 
+use WebberZone\Knowledge_Base\Frontend\Language_Handler;
 use WebberZone\Knowledge_Base\Util\Cache;
 use WebberZone\Knowledge_Base\Util\Helpers;
 
@@ -228,7 +229,8 @@ public static function fetch_terms( $taxonomy, $query_args = array(), $meta_quer
 
 		if ( $cache_enabled ) {
 			// Create a transient-based cache key for non-term-specific queries.
-			$transient_key = 'wzkb_fetch_terms_' . md5( wp_json_encode( $args ) );
+			$lang          = Language_Handler::get_current_language();
+			$transient_key = 'wzkb_fetch_terms_' . md5( wp_json_encode( $args ) . '_' . $lang );
 
 			// Try to get from transient cache first.
 			$cached_terms = get_transient( $transient_key );
@@ -577,8 +579,10 @@ public static function get_term_posts( $term ): \WP_Query {
 
 		// Support caching to speed up retrieval.
 		if ( $cache_enabled ) {
-			$meta_key = Cache::get_key( $args );
-			$query    = Cache::get( $term->term_id, $meta_key );
+			$lang           = Language_Handler::get_current_language();
+			$cache_key_args = $lang ? array_merge( $args, array( 'lang' => $lang ) ) : $args;
+			$meta_key       = Cache::get_key( $cache_key_args );
+			$query          = Cache::get( $term->term_id, $meta_key );
 		}
 
 		if ( empty( $query ) ) {

includes/frontend/class-language-handler.php

@@ -17,6 +17,8 @@
 /**
  * Language handler class.
  *
+ * Handles i18n, WPML integration, and Polylang integration.
+ *
  * @since 2.3.0
  */
 class Language_Handler {
@@ -40,4 +42,55 @@ public function __construct() {
 	public static function load_plugin_textdomain() {
 		load_plugin_textdomain( 'knowledgebase', false, WZKB_PLUGIN_DIR . '/languages/' );
 	}
+
+	/**
+	 * Translate a term ID to the current language.
+	 *
+	 * Widget and shortcode settings store the term ID saved by the admin in the
+	 * default language. On a non-default-language page the stored ID must be
+	 * resolved to the equivalent term in the current language before use.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param int    $term_id  Term ID in the default language.
+	 * @param string $taxonomy Taxonomy slug.
+	 * @return int Translated term ID, or the original if no translation exists.
+	 */
+	public static function get_translated_term_id( int $term_id, string $taxonomy ): int {
+		if ( ! $term_id ) {
+			return $term_id;
+		}
+
+		// WPML.
+		if ( defined( 'ICL_SITEPRESS_VERSION' ) ) {
+			return (int) apply_filters( 'wpml_object_id', $term_id, $taxonomy, true );
+		}
+
+		// Polylang.
+		if ( defined( 'POLYLANG_VERSION' ) ) {
+			$translated = pll_get_term( $term_id );
+			return $translated ? (int) $translated : $term_id;
+		}
+
+		return $term_id;
+	}
+
+	/**
+	 * Return the current language slug, or an empty string when no multilingual plugin is active.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @return string Language slug (e.g. 'en', 'fr') or '' if not multilingual.
+	 */
+	public static function get_current_language(): string {
+		if ( defined( 'ICL_SITEPRESS_VERSION' ) ) {
+			return (string) apply_filters( 'wpml_current_language', '' );
+		}
+
+		if ( defined( 'POLYLANG_VERSION' ) ) {
+			return (string) pll_current_language();
+		}
+
+		return '';
+	}
 }

includes/frontend/class-related.php

@@ -166,6 +166,48 @@ public static function get_related_articles_query( $args = array() ) {
 			self::sort_query_by_relevance( $query, $category_ids, $tag_ids, $args );
 		}
 
+		// Fallback: if no results and the post has categories, widen the search to
+		// sibling sections — other sections belonging to the same product.
+		if ( 0 === $query->post_count && ! empty( $category_ids ) ) {
+			$products    = get_the_terms( $post, 'wzkb_product' );
+			$product_ids = ( $products && ! is_wp_error( $products ) ) ? wp_list_pluck( $products, 'term_id' ) : array();
+
+			$sibling_args = $related_args;
+
+			if ( ! empty( $product_ids ) ) {
+				// Multi-product: restrict to the same product, exclude the current section.
+				// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_tax_query
+				$sibling_args['tax_query'] = array(
+					'relation' => 'AND',
+					array(
+						'taxonomy' => 'wzkb_product',
+						'field'    => 'term_id',
+						'terms'    => $product_ids,
+					),
+					array(
+						'taxonomy' => 'wzkb_category',
+						'field'    => 'term_id',
+						'terms'    => $category_ids,
+						'operator' => 'NOT IN',
+					),
+				);
+			} else {
+				// Single-product: all sections are siblings — exclude only the current section.
+				// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_tax_query
+				$sibling_args['tax_query'] = array(
+					array(
+						'taxonomy' => 'wzkb_category',
+						'field'    => 'term_id',
+						'terms'    => $category_ids,
+						'operator' => 'NOT IN',
+					),
+				);
+			}
+
+			$query = new \WP_Query( $sibling_args );
+			self::sort_query_by_relevance( $query, $category_ids, $tag_ids, $args );
+		}
+
 		/**
 		 * Filters the cache TTL for related article queries.
 		 *

includes/functions.php

@@ -209,6 +209,11 @@ function wzkb_get_kb_url() {
 		return home_url( '/' );
 	}
 
+	$archive_link = get_post_type_archive_link( 'wz_knowledgebase' );
+	if ( $archive_link ) {
+		return $archive_link;
+	}
+
 	$kb_slug = \wzkb_get_option( 'kb_slug', 'knowledgebase' );
 	return home_url( "/{$kb_slug}/" );
 }

includes/widgets/class-articles-widget.php

@@ -8,6 +8,7 @@
 namespace WebberZone\Knowledge_Base\Widgets;
 
 use WebberZone\Knowledge_Base\Frontend\Display;
+use WebberZone\Knowledge_Base\Frontend\Language_Handler;
 
 // If this file is called directly, abort.
 if ( ! defined( 'WPINC' ) ) {
@@ -171,10 +172,11 @@ public function widget( $args, $instance ) {
 
 		// Handle product_id if set.
 		if ( ! empty( $instance['product_id'] ) ) {
-			$kb_args['product'] = (int) $instance['product_id'];
+			$kb_args['product'] = Language_Handler::get_translated_term_id( (int) $instance['product_id'], 'wzkb_product' );
 			$list_of_posts      = Display::get_knowledge_base_loop( 0, 1, true, $kb_args );
 		} elseif ( ! empty( $instance['term_id'] ) ) {
-			$term = get_term( $instance['term_id'], 'wzkb_category' );
+			$term_id = Language_Handler::get_translated_term_id( (int) $instance['term_id'], 'wzkb_category' );
+			$term    = get_term( $term_id, 'wzkb_category' );
 
 			if ( empty( $term ) || is_wp_error( $term ) ) {
 				return;

includes/widgets/class-products-widget.php

@@ -8,6 +8,7 @@
 namespace WebberZone\Knowledge_Base\Widgets;
 
 use WebberZone\Knowledge_Base\Frontend\Display;
+use WebberZone\Knowledge_Base\Frontend\Language_Handler;
 
 if ( ! defined( 'WPINC' ) ) {
 	die;
@@ -116,7 +117,7 @@ public function widget( $args, $instance ) {
 
 		$title      = ( ! empty( $instance['title'] ) ) ? $instance['title'] : '';
 		$title      = apply_filters( 'widget_title', $title, $instance, $this->id_base );
-		$product_id = ! empty( $instance['product_id'] ) ? (int) $instance['product_id'] : 0;
+		$product_id = Language_Handler::get_translated_term_id( ! empty( $instance['product_id'] ) ? (int) $instance['product_id'] : 0, 'wzkb_product' );
 		$depth      = isset( $instance['depth'] ) ? (int) $instance['depth'] : -1;
 
 		$output  = '';

includes/widgets/class-sections-widget.php

@@ -7,6 +7,8 @@
 
 namespace WebberZone\Knowledge_Base\Widgets;
 
+use WebberZone\Knowledge_Base\Frontend\Language_Handler;
+
 // If this file is called directly, abort.
 if ( ! defined( 'WPINC' ) ) {
 	die;
@@ -165,8 +167,8 @@ public function widget( $args, $instance ) {
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
 
-		$product_id = isset( $instance['product_id'] ) ? (int) $instance['product_id'] : 0;
-		$term_id    = ! empty( $instance['term_id'] ) ? (int) $instance['term_id'] : 0;
+		$product_id = Language_Handler::get_translated_term_id( isset( $instance['product_id'] ) ? (int) $instance['product_id'] : 0, 'wzkb_product' );
+		$term_id    = Language_Handler::get_translated_term_id( ! empty( $instance['term_id'] ) ? (int) $instance['term_id'] : 0, 'wzkb_category' );
 
 		$arguments = array(
 			'is_widget'      => 1,