This article documents the language CRUD layer of WPEstate Translate (text domain wpr-translate). It covers where language records live, how they are normalized, which helpers resolve the current language, and the admin view that writes to them. The sibling user-facing article shows the screen itself; this page is the code map behind it. For the product angle see the multi-language real estate website guide.
Source Files
| File | Role |
|---|---|
| includes/language-manager.php | Public API – get, resolve, and set the current language. Thin wrappers over the language-context modules. |
| includes/language-context/registry.php | Reads wpr_translate_languages once per request, normalizes it, finds languages and the default. Cache cleared on update_option_wpr_translate_languages. |
| includes/language-context/resolution.php | Side-effect-free policy for front end, URL prefix, AJAX and wp-admin. |
| includes/language-context/activation.php | Activates a request language: state, compatibility mirrors, locale and text-domain reloads. |
| includes/language-context/urls.php | Default-language identity and URL slug policy. |
| includes/language-context/content.php, wp-adapters.php, state.php | Post language lookup, WordPress input reads (AJAX lang, admin user meta), request-scoped state store. |
| includes/language-manager-helpers.php | wpr_translate_normalize_language() and wpr_translate_debug_log(). |
| includes/language-catalog.php | Hardcoded ISO catalog returned by wpr_translate_language_catalog_by_code(). |
| includes/language-rewrite-bases.php | Per-language URL bases for estate_property, estate_agent, estate_agency and estate_developer. |
| includes/main-lang-functions.php | Entry points used across the plugin, such as wpr_translate_get_active_languages() and wpr_translate_get_current_language(). |
| includes/functions-language.php | Legacy compatibility wrappers and the wpr_current_language / wpr_object_id filters. |
| includes/admin/views/languages.php | Settings API form – posts to options.php with setting group wpr_translate_languages. |
| includes/admin/views/languages-helpers.php | Prepares the view payload (sorts, merges catalog, computes next_index). |
Storage
| Option | Shape |
|---|---|
| wpr_translate_languages | Numerically indexed array of language payloads. Written by the Languages form via Settings API (register_setting() with sanitizer wpr_translate_admin_sanitize_languages). |
| wpr_translate_language_catalog | Full ISO catalog snapshot, written once by the activator so lookups do not depend on the PHP file. |
The default language is stored only as the is_default flag on one row of wpr_translate_languages. There is no default_language key in wpr_translate_settings; the Settings screen shows the current default with a link to the Languages Manager.
Language Payload Shape
The sanitizer stores these keys on every row:
array(
'code' => 'en',
'name' => 'English',
'locale' => 'en_US',
'slug' => 'en',
'flag' => 'us',
'display_order' => 0,
'is_default' => true,
'is_active' => true,
'is_public' => true,
'date_format' => 'F j, Y',
'time_format' => 'g:i a',
'rewrite_bases' => array( 'estate_property' => 'propiedad' ), // optional overrides
)
wpr_translate_normalize_language() guarantees code, locale, name, slug, flag, is_default, is_active, is_public, date_format and time_format (missing flags default to false). It sanitizes slug with sanitize_title(). display_order and rewrite_bases are passed through as stored.
Public API
| Function | Purpose |
|---|---|
| wpr_translate_get_languages() | All stored languages, normalized, cached per request. No active/public filter. |
| wpr_translate_get_active_languages( $public_only = true ) | Filtered list: is_active required; is_public required when $public_only is true. |
| wpr_translate_get_default_language() | First active row with is_default set, or the first active row as fallback; null when no language is active. |
| wpr_translate_get_language( $identifier ) | Lookup by slug, then code, then locale. Case-insensitive, underscore/hyphen tolerant for locales. |
| wpr_translate_get_current_admin_language() | wp-admin language: the user meta wpr_translate_admin_language when it names an active language (private allowed), else the default. |
| wpr_translate_resolve_preferred_language() | AJAX $_REQUEST[‘lang’] (active language) > wp-admin preference (in admin) > default language. |
| wpr_translate_get_post_language( $post_id ) | Language of a post, resolved through wpr_translation_resolve_post_language_code() (translation metadata, legacy trid rows as fallback). Cached per request. |
| wpr_translate_get_context_language( $post_id = 0 ) | Post language when available, otherwise the language the router set for this request, otherwise the preferred language, otherwise default. |
| wpr_translate_set_current_language( $language, $options ) | Activates the request language: stores it in the context state and $GLOBALS[‘wpr_translate_current_language’], mirrors the slug onto WP_Estate_Translation::$current_language, and with reload_theme_translations reloads theme text domains and core translations for the locale (once per locale per request). Passing an empty value clears the state. |
| wpr_translate_get_language_slug( $language ) | URL slug, empty string for the default language; falls back to the code when a non-default language has no slug. |
| wpr_translate_is_default_language( $language ) | True when the payload has is_default, or its code, locale or slug (in that order) equals the default’s. |
Preferred Language Resolution
wpr_translate_resolve_preferred_language() reads in this order:
- If no active language exists, return null.
- During AJAX, the lang request parameter that public-ajax-language.js appends to front-end AJAX calls, if it names an active language.
- In wp-admin, wpr_translate_get_current_admin_language().
- Otherwise the default language.
Cookies and the browser Accept-Language header are not consulted. On the front end, the language comes from the URL prefix set by the router.
The Languages Admin Form
The view at includes/admin/views/languages.php posts to options.php with setting group wpr_translate_languages. Form fields follow this pattern:
wpr_translate_languages[0][code] wpr_translate_languages[0][name] wpr_translate_languages[0][locale] wpr_translate_languages[0][slug] wpr_translate_languages[0][flag] wpr_translate_languages[0][is_default] wpr_translate_languages[0][is_active] wpr_translate_languages[0][is_public] wpr_translate_languages[0][display_order] wpr_translate_languages[0][date_format] wpr_translate_languages[0][time_format] wpr_translate_languages[0][rewrite_bases][estate_property]
A hidden input with value 0 precedes each checkbox so unchecked boxes still submit a value. The radio wpr-language-default is a UI-only control that sets the row’s is_default field.
The drag-and-drop handle writes back into display_order via the admin script bundle wpr-translate-admin.
What the Sanitizer Enforces
- Rows without a code are dropped; duplicate codes keep the last row.
- Rows are sorted by display_order, then renumbered 0..n.
- Exactly one default: the first row flagged is_default, else the first active row, else the first row. The default is always forced active.
- rewrite_bases are slugified; if two post types would share a base within one language, all overrides for that language are dropped and the error “Each post type needs a different URL base within a language.” is shown.
- A language that still has content (posts with _wpr_language, terms with wpr_term_language, menus with wpr_menu_language, or translated strings) cannot be removed. The save is refused with “The language “%s” still has translated content and was not removed. Delete its translations first.”
- Language packs are downloaded for newly added locales, and rewrite rules are flushed when the list changes.
After the option is saved, update_option_wpr_translate_languages listeners clear the registry cache and move nav menu assignments when the default language changes (menus that followed the old default are pinned to it).
Catalog
wpr_translate_language_catalog_by_code() in language-catalog.php returns the full hardcoded catalog – over 200 ISO-keyed entries, each with code, locale, name, slug, and flag. On activation the array is copied to wpr_translate_language_catalog so admin screens can read it without parsing the PHP file.
Theme Bridge
For backwards compatibility with the WPResidence theme’s own translation helpers, wpr_translate_set_current_language() mirrors the active slug onto the static property WP_Estate_Translation::$current_language (null for the default language). Any theme code that checks that property keeps working without being rewritten.
Debug Logging
wpr_translate_debug_log() writes to the PHP error log only when WPR_DEBUG_MODE is defined as true in wp-config.php. The language-context modules log every resolution step through it.
Extending Safely
- Always funnel lookups through the helpers – do not read wpr_translate_languages directly. The helpers normalize legacy payloads and guard against non-array values.
- Do not pass language names through sanitize_title(). Names may be Cyrillic, Arabic, or Chinese; only the slug is ASCII.
- When adding a language programmatically, merge it into get_option(‘wpr_translate_languages’, array()) and call update_option(). The registered sanitizer runs, enforces a single default and flushes rewrite rules.
- To change the default language in code, move the is_default flag between rows. Writing a default_language setting has no effect.
- Test against wpr_translate_get_active_languages(false) (includes non-public) before gating UI on count() > 1.
Related Articles
- Settings Page – the global settings option shape.
- URL Structure & Permalinks – how slugs become URL prefixes.
- Translation Linking (trid system) – how language codes map to posts and terms.
See the multi-language real estate website page for product context.