Language Hierarchy
Allows users to configure inheritance between languages on a multilingual Drupal site, enabling automatic translation fallback chains.
language_hierarchy
Install
composer require 'drupal/language_hierarchy:^2.0'
Overview
Language Hierarchy provides a powerful fallback mechanism for multilingual Drupal sites. It allows administrators to define parent-child relationships between languages, creating a hierarchy where content and configuration automatically fall back to ancestor languages when translations are not available in a specific language variant.
This module is particularly useful for sites with regional language variants (e.g., Spanish for Mexico vs. general Spanish, German for Germany vs. general German) where you want to share translations between related languages while allowing language-specific overrides. When a translation is missing in a specific language like es-MX (Spanish Mexico), the module will automatically look for translations in its parent language es (Spanish), and then continue up the chain as configured.
The module integrates deeply with Drupal's language system, extending the Language module's configuration forms to allow administrators to set up language hierarchies through a visual drag-and-drop interface. It also provides Views integration for filtering and sorting content by language relevance within the hierarchy.
Features
- Configure fallback language for each language through a hierarchical tree structure with drag-and-drop reordering
- Automatic translation fallback for both content entities and configuration translations
- Integration with Drupal's core Locale module for string translation fallback support
- Views filter plugin to show only the most specific translation for the current content language
- Views sort plugin to order content by language relevance within the configured hierarchy
- Config Translation integration that correctly distinguishes between direct translations and inherited fallback translations
- URL fixing for entity links to prevent linking to fallback translations when viewing content in a specific language
- Query alteration for path aliases to respect language hierarchy priority ordering
- Database table (language_hierarchy_priority) for optimized query performance when determining language priority
Use Cases
Regional Spanish Variants
A site has content in Spanish (es), Spanish for Mexico (es-MX), and Spanish for Spain (es-ES). Configure es-MX and es-ES to fall back to es. When viewing the site in es-MX, if specific content is not translated to Mexican Spanish, the general Spanish translation will be shown automatically. This reduces translation workload while allowing regional customizations.
German-speaking Countries
A site targets Germany (de-DE), Austria (de-AT), and Switzerland (de-CH), with English as the ultimate fallback. Configure: de-DE → de → en, de-AT → de → en, de-CH → de → en. Common German content is translated once, with country-specific variations only where needed.
Configuration Translation Inheritance
System configuration like site name, email templates, or field labels can be translated once in a parent language and automatically inherited by child languages. Only language-specific overrides need to be created in the child languages.
Views with Language-Aware Content Listing
Create a View that displays content in the most relevant language for the current user. Use the 'Most relevant translation' filter and 'Content language relevance' sort to show content translated to the user's specific language first, falling back to parent language translations, then language-neutral content.
Locale String Translation Sharing
Interface translations (t() strings) can be shared across language variants. Translate UI strings once in the parent language, and they automatically appear in all child languages unless specifically overridden.
Tips
- Use the drag-and-drop interface on the Languages page for quick hierarchy management rather than editing each language individually
- The fallback chain can be multiple levels deep - for example, es-MX can fall back to es which falls back to en
- When creating Views, combine the 'Most relevant translation' filter with the 'Content language relevance' sort for optimal results
- Set the 'language_hierarchy_fallback' URL option to TRUE when you intentionally want to link to a fallback translation
- Language-neutral content (und) is always included as a final fallback candidate except during locale_lookup operations
- The priority table is automatically maintained - you don't need to manually manage it
Technical Details
Admin Pages 2
/admin/config/regional/language
Configure language hierarchy relationships using a hierarchical tree interface. Languages can be reordered and parent languages can be assigned using drag-and-drop functionality. The table shows indentation representing hierarchy depth, parent language selection dropdowns, and language IDs.
/admin/config/regional/language/edit/{language}
Edit individual language settings including the fallback language configuration.
Hooks 12
hook_language_fallback_candidates_alter
Builds the fallback chain for a language by traversing the language hierarchy. This is the core mechanism that provides fallback functionality across Drupal's language system.
hook_query_path_alias_language_fallback_alter
Orders the fallback candidates when querying path aliases by joining the language_hierarchy_priority table and sorting by priority.
hook_query_language_hierarchy_limit_alter
Complex correlated subquery implementation that limits results to only show the most specific translations. Used by Views filter plugin.
hook_form_language_admin_edit_form_alter
Adds the 'Translation fallback language' select field to the language edit form.
hook_form_language_admin_overview_form_alter
Transforms the flat language list into a hierarchical tree with drag-and-drop reordering and parent assignment capabilities.
hook_configurable_language_insert
Updates language hierarchy priorities when a new language is created.
hook_configurable_language_update
Updates language hierarchy priorities when a language is modified.
hook_configurable_language_delete
Updates language hierarchy priorities when a language is deleted.
hook_preprocess_node
Fixes node URLs to not point to fallback translations when viewing content in a specific language.
hook_preprocess_taxonomy_term
Fixes taxonomy term URLs to not point to fallback translations.
hook_preprocess_image_formatter
Fixes image link URLs to not point to fallback translations.
hook_preprocess_responsive_image_formatter
Fixes responsive image link URLs to not point to fallback translations.
Troubleshooting 5
Verify that the fallback language is correctly configured on the language entity. Check Administration > Configuration > Regional and language > Languages and ensure the Parent column shows the expected parent language. Also verify that the parent language actually has the translation you expect to fall back to.
The 'Most relevant translation' filter only supports SQL query backend. Ensure your View is using the SQL query plugin. Also check that the filter is enabled (checkbox is checked) in the filter configuration.
This should be handled automatically by the module's controller override. If not working, ensure the Config Translation module is enabled and clear all caches. The module only registers its route subscriber when Config Translation is enabled.
The string translation fallback only works when the Locale module is enabled. The module dynamically registers the StringDatabaseStorageDecorator service only when Locale is available. Enable Locale and rebuild the container.
Language priorities are stored in the language_hierarchy_priority database table. Run language_hierarchy_update_priorities() or trigger a language entity save to recalculate. This happens automatically on language CRUD operations and config import.