JPKCom Simple Lang

Lang

Table of Contents

Constants

JPKCOM_SIMPLELANG_ABILITY_CATEGORY  : mixed = 'jpkcom-content'
Ability category.
JPKCOM_SIMPLELANG_ABILITY_INPUT_KEYS  : mixed = ['jpkcom-simple-lang/list-languages' => [], 'jp...
Top-level input keys each ability declares.
JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_DEFAULT  : mixed = 20
Default page size for the set check.
JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_MAX  : mixed = 100
Largest page size honoured.
JPKCOM_SIMPLELANG_ABILITY_SCAN_LIMIT  : mixed = 2000
Largest number of linked posts examined in one call.

Functions

jpkcom_simplelang_abilities_enabled()  : bool
Decide whether the abilities should be registered at all.
jpkcom_simplelang_ability_log()  : void
Write a debug line, and only with WP_DEBUG.
jpkcom_simplelang_ability_error()  : WP_Error
Build a WP_Error carrying an HTTP status.
jpkcom_simplelang_ability_boundary()  : array<string, mixed>|WP_Error
Turn a Throwable out of a callback into a WP_Error.
jpkcom_simplelang_ability_json_object()  : array<string, mixed>|stdClass
Wrap an empty map so it encodes as {} rather than [].
jpkcom_simplelang_ability_capability()  : bool
Check the capability required to run an ability.
jpkcom_simplelang_ability_meta()  : array<string, mixed>
Build the meta array for an ability.
jpkcom_simplelang_ability_normalise_input()  : array<string, mixed>|null
Bring the value core hands the callback into array form.
jpkcom_simplelang_ability_validate_input_keys()  : true|WP_Error
Refuse a top-level input key the ability does not declare.
jpkcom_simplelang_ability_enabled_post_types()  : array<string|int, string>
The post types language selection is enabled for.
jpkcom_simplelang_ability_describe_locale()  : array<string, mixed>
Describe a locale the way the front end resolves it.
jpkcom_simplelang_ability_list_languages_inner()  : array<string, mixed>|WP_Error
Report which languages this site actually uses.
jpkcom_simplelang_ability_build_sets()  : array{sets: array, scanned: int, truncated: bool}
Collect the translation sets on this site.
jpkcom_simplelang_ability_inspect_set()  : array<string, mixed>
Report what the hreflang output for one set will and will not contain.
jpkcom_simplelang_ability_check_sets_inner()  : array<string, mixed>|WP_Error
Report the translation sets whose hreflang output comes out incomplete.
jpkcom_simplelang_ability_permission_list_languages()  : bool
Permission callback for list-languages.
jpkcom_simplelang_ability_permission_check_sets()  : bool
Permission callback for check-translation-sets.
jpkcom_simplelang_ability_list_languages()  : array<string, mixed>|WP_Error
Execute callback for jpkcom-simple-lang/list-languages.
jpkcom_simplelang_ability_check_sets()  : array<string, mixed>|WP_Error
Execute callback for jpkcom-simple-lang/check-translation-sets.
jpkcom_simplelang_get_ability_definitions()  : array<string, array<string, mixed>>
Build the registration arguments for both abilities.
jpkcom_simplelang_register_ability_category()  : void
Register the shared category, unless a sibling plugin already did.
jpkcom_simplelang_register_abilities()  : void
Register both abilities.
jpkcom_simplelang_sanitize_post_types()  : array<int, string>
Sanitize post types array
jpkcom_simplelang_enabled_post_types_field()  : void
Render enabled post types field
jpkcom_simplelang_settings_page()  : void
Render settings page
jpkcom_simplelang_get_language_code()  : string
Convert locale to language code
jpkcom_simplelang_get_bcp47()  : string
Convert a WordPress locale to a BCP 47 language tag
jpkcom_simplelang_get_current_language()  : string|null
Get current frontend language
jpkcom_simplelang_get_site_default_locale()  : string
Get site default locale
jpkcom_simplelang_get_language_name()  : string
Get language name from locale
jpkcom_simplelang_group_posts_by_language()  : array<string, array<int, WP_Post>>
Group posts by language
jpkcom_simplelang_validate_translations()  : array<string|int, int>
Validate translation links
jpkcom_simplelang_get_translation_posts()  : array<string|int, WP_Post>
Get translation posts efficiently
jpkcom_simplelang_sync_translations()  : void
Sync translation links bidirectionally
jpkcom_simplelang_render_translations_meta_box()  : void
Render translation links meta box
jpkcom_simplelang_output_hreflang_tags()  : void
Generate and output hreflang tags
jpkcom_simplelang_render_meta_box()  : void
Render language selection meta box
jpkcom_simplelang_is_valid_locale()  : bool
Check whether a locale may be stored as a post language
jpkcom_simplelang_get_post_language()  : string|null
Get post language
jpkcom_simplelang_get_oxygen_language_options()  : array<string, string>
Get language options for Oxygen Builder
jpkcom_simplelang_oxygen_post_language_is()  : bool
Oxygen condition callback: Post language is specific value
jpkcom_simplelang_oxygen_has_custom_language()  : bool
Oxygen condition callback: Post has custom language
jpkcom_simplelang_oxygen_uses_default_language()  : bool
Oxygen condition callback: Post uses default language

Constants

JPKCOM_SIMPLELANG_ABILITY_CATEGORY

Ability category.

public mixed JPKCOM_SIMPLELANG_ABILITY_CATEGORY = 'jpkcom-content'

Categories are global and registration is FIRST-WINS, so this goes through wp_has_ability_category() rather than assuming.

Tags
since
1.3.0

JPKCOM_SIMPLELANG_ABILITY_INPUT_KEYS

Top-level input keys each ability declares.

public mixed JPKCOM_SIMPLELANG_ABILITY_INPUT_KEYS = ['jpkcom-simple-lang/list-languages' => [], 'jpkcom-simple-lang/check-translation-sets' => ['page', 'per_page']]

Cross-checked against the registered schemas by tests/test-abilities.php. additionalProperties is deliberately not declared on the schema that carries properties: validate_input() runs before the execute callback and would preempt the guard below, replacing a message naming the accepted keys with core's "not a valid property of the object".

Tags
since
1.3.0

JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_DEFAULT

Default page size for the set check.

public mixed JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_DEFAULT = 20
Tags
since
1.3.0

JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_MAX

Largest page size honoured.

public mixed JPKCOM_SIMPLELANG_ABILITY_PER_PAGE_MAX = 100
Tags
since
1.3.0

JPKCOM_SIMPLELANG_ABILITY_SCAN_LIMIT

Largest number of linked posts examined in one call.

public mixed JPKCOM_SIMPLELANG_ABILITY_SCAN_LIMIT = 2000

Building the sets means reading every post that carries a translation link, which is unbounded on a large site. The cap is reported back rather than applied silently: an answer that stopped early while looking complete is the failure this field exists to prevent.

Tags
since
1.3.0

Functions

jpkcom_simplelang_abilities_enabled()

Decide whether the abilities should be registered at all.

jpkcom_simplelang_abilities_enabled() : bool
Tags
since
1.3.0
Return values
bool —

True when registration should proceed.

jpkcom_simplelang_ability_log()

Write a debug line, and only with WP_DEBUG.

jpkcom_simplelang_ability_log(string $message) : void
Parameters
$message : string

Message.

Tags
since
1.3.0

jpkcom_simplelang_ability_error()

Build a WP_Error carrying an HTTP status.

jpkcom_simplelang_ability_error(string $code, string $message[, int $status = 400 ]) : WP_Error

Without data['status'] rest_ensure_response() defaults to 500, and a 5xx tells an agent "transient fault, retry unchanged" - the opposite of what a caller mistake needs to hear.

Parameters
$code : string

Error code.

$message : string

Message.

$status : int = 400

HTTP status.

Tags
since
1.3.0
Return values
WP_Error —

Error.

jpkcom_simplelang_ability_boundary()

Turn a Throwable out of a callback into a WP_Error.

jpkcom_simplelang_ability_boundary(callable $body, string $ability) : array<string, mixed>|WP_Error
Parameters
$body : callable

Callback.

$ability : string

Ability name.

Tags
since
1.3.0
Return values
array<string, mixed>|WP_Error —

Result or error.

jpkcom_simplelang_ability_json_object()

Wrap an empty map so it encodes as {} rather than [].

jpkcom_simplelang_ability_json_object(array<string, mixed> $map) : array<string, mixed>|stdClass
Parameters
$map : array<string, mixed>

Map.

Tags
since
1.3.0
Return values
array<string, mixed>|stdClass —

Map, or an empty object.

jpkcom_simplelang_ability_capability()

Check the capability required to run an ability.

jpkcom_simplelang_ability_capability(string $ability) : bool

edit_posts, not read. This reports an editorial and SEO condition of the site - which pages are annotated for which language, and where that annotation comes out incomplete - and it names unpublished and dangling posts while doing so. That is not visitor-facing content.

Parameters
$ability : string

Ability name.

Tags
since
1.3.0
Return values
bool —

True when the current user may run it.

jpkcom_simplelang_ability_meta()

Build the meta array for an ability.

jpkcom_simplelang_ability_meta(string $ability) : array<string, mixed>

All three annotations explicit: they default to null and the REST run controller derives the HTTP verb from them, so without readonly the run route would be POST-only.

Parameters
$ability : string

Ability name.

Tags
since
1.3.0
Return values
array<string, mixed> —

Meta array.

jpkcom_simplelang_ability_normalise_input()

Bring the value core hands the callback into array form.

jpkcom_simplelang_ability_normalise_input(mixed $input) : array<string, mixed>|null

normalize_input() substitutes the schema's top-level default when the input is exactly null, and that default is a stdClass - so the callback receives an object and must read it.

Parameters
$input : mixed

Raw input.

Tags
since
1.3.0
Return values
array<string, mixed>|null —

Array form, or null when unusable.

jpkcom_simplelang_ability_validate_input_keys()

Refuse a top-level input key the ability does not declare.

jpkcom_simplelang_ability_validate_input_keys(array<string, mixed> $input, array<string|int, string> $allowed) : true|WP_Error

On EVERY ability, not a subset: a caller that learned the refusal on one assumes it everywhere, and the ability that silently accepts is the one it will trust.

Parameters
$input : array<string, mixed>

Raw input.

$allowed : array<string|int, string>

Declared keys.

Tags
since
1.3.0
Return values
true|WP_Error —

True when every key is declared.

jpkcom_simplelang_ability_enabled_post_types()

The post types language selection is enabled for.

jpkcom_simplelang_ability_enabled_post_types() : array<string|int, string>

Reads the same option and the same default the rest of the plugin reads, rather than restating either.

Tags
since
1.3.0
Return values
array<string|int, string> —

Post type names.

jpkcom_simplelang_ability_describe_locale()

Describe a locale the way the front end resolves it.

jpkcom_simplelang_ability_describe_locale(string $locale, array<string|int, string> $installed) : array<string, mixed>

installed matters more than it looks: a locale whose language pack was removed stays in the post meta, and switch_to_locale() then returns false, so the front end deliberately does NOT switch. The page keeps the site language while its meta still claims another one.

Parameters
$locale : string

Locale, or '' for "no language of its own".

$installed : array<string|int, string>

Installed locales.

Tags
since
1.3.0
Return values
array<string, mixed> —

Description.

jpkcom_simplelang_ability_list_languages_inner()

Report which languages this site actually uses.

jpkcom_simplelang_ability_list_languages_inner([mixed $input = null ]) : array<string, mixed>|WP_Error
Parameters
$input : mixed = null

Ability input.

Tags
since
1.3.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_simplelang_ability_build_sets()

Collect the translation sets on this site.

jpkcom_simplelang_ability_build_sets(array<string|int, string> $types) : array{sets: array, scanned: int, truncated: bool}

A set is a post plus everything it links to. Because the links are bidirectional, the same set is reachable from each of its members, so sets are deduplicated by their sorted member list.

Parameters
$types : array<string|int, string>

Enabled post types.

Tags
since
1.3.0
Return values
array{sets: array, scanned: int, truncated: bool} —

Sets.

jpkcom_simplelang_ability_inspect_set()

Report what the hreflang output for one set will and will not contain.

jpkcom_simplelang_ability_inspect_set(array<string|int, int> $members, string $default_tag, array<string|int, string> $installed) : array<string, mixed>

Every finding below is derived from what the emitter does, not from an opinion about what it should do:

  • It keys entries by BCP 47 tag and keeps the FIRST per tag, so two members resolving to one tag yield one entry and the other URL is annotated nowhere. Which of the two survives depends on the order the posts come back in, so this reports the collision and does NOT claim a winner.
  • A member with no language of its own is read as the site default, so it collides with an explicit member in that language rather than being ignored.
  • x-default is emitted only when some member carries the site default tag.
  • Only published posts are fetched, so an unpublished member never appears.
Parameters
$members : array<string|int, int>

Member post IDs.

$default_tag : string

Site default BCP 47 tag.

$installed : array<string|int, string>

Installed locales.

Tags
since
1.3.0
Return values
array<string, mixed> —

Report for this set.

jpkcom_simplelang_ability_check_sets_inner()

Report the translation sets whose hreflang output comes out incomplete.

jpkcom_simplelang_ability_check_sets_inner([mixed $input = null ]) : array<string, mixed>|WP_Error
Parameters
$input : mixed = null

Ability input.

Tags
since
1.3.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_simplelang_ability_permission_list_languages()

Permission callback for list-languages.

jpkcom_simplelang_ability_permission_list_languages([mixed $input = null ]) : bool
Parameters
$input : mixed = null

Validated input, unused.

Tags
since
1.3.0
Return values
bool —

True when the current user may run it.

jpkcom_simplelang_ability_permission_check_sets()

Permission callback for check-translation-sets.

jpkcom_simplelang_ability_permission_check_sets([mixed $input = null ]) : bool
Parameters
$input : mixed = null

Validated input, unused.

Tags
since
1.3.0
Return values
bool —

True when the current user may run it.

jpkcom_simplelang_ability_list_languages()

Execute callback for jpkcom-simple-lang/list-languages.

jpkcom_simplelang_ability_list_languages([mixed $input = null ]) : array<string, mixed>|WP_Error
Parameters
$input : mixed = null

Ability input.

Tags
since
1.3.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_simplelang_ability_check_sets()

Execute callback for jpkcom-simple-lang/check-translation-sets.

jpkcom_simplelang_ability_check_sets([mixed $input = null ]) : array<string, mixed>|WP_Error
Parameters
$input : mixed = null

Ability input.

Tags
since
1.3.0
Return values
array<string, mixed>|WP_Error —

Result.

jpkcom_simplelang_get_ability_definitions()

Build the registration arguments for both abilities.

jpkcom_simplelang_get_ability_definitions() : array<string, array<string, mixed>>

Reads no WordPress state and touches no registry, which is what lets the CI harness assert the shape of these arrays without a WordPress installation.

Tags
since
1.3.0
Return values
array<string, array<string, mixed>> —

Ability name => registration args.

jpkcom_simplelang_register_ability_category()

Register the shared category, unless a sibling plugin already did.

jpkcom_simplelang_register_ability_category() : void
Tags
since
1.3.0

jpkcom_simplelang_register_abilities()

Register both abilities.

jpkcom_simplelang_register_abilities() : void

wp_register_ability() returns null on EVERY failure path and reports only through _doing_it_wrong(), which is silent in production - and so is the debug log without WP_DEBUG.

Tags
since
1.3.0

jpkcom_simplelang_sanitize_post_types()

Sanitize post types array

jpkcom_simplelang_sanitize_post_types(array<int, string>|null $value) : array<int, string>

Ensures only valid post types are saved in the settings.

Parameters
$value : array<int, string>|null

The post types array to sanitize.

Tags
since
1.0.0
Return values
array<int, string> —

Sanitized array of valid post types.

jpkcom_simplelang_enabled_post_types_field()

Render enabled post types field

jpkcom_simplelang_enabled_post_types_field() : void

Displays checkboxes for all public post types.

Tags
since
1.0.0

jpkcom_simplelang_settings_page()

Render settings page

jpkcom_simplelang_settings_page() : void

Displays the admin settings page for Simple Lang plugin.

Tags
since
1.0.0

jpkcom_simplelang_get_language_code()

Convert locale to language code

jpkcom_simplelang_get_language_code(string $locale) : string

Converts a locale string (e.g., de_DE) to a language code (e.g., de).

Kept for backwards compatibility. For markup that needs a language tag use jpkcom_simplelang_get_bcp47() instead — a bare subtag cannot express de-DE versus de-AT, and hreflang needs that distinction.

Parameters
$locale : string

The locale string.

Tags
since
1.0.0
Return values
string —

The language code.

jpkcom_simplelang_get_bcp47()

Convert a WordPress locale to a BCP 47 language tag

jpkcom_simplelang_get_bcp47(string $locale) : string

de_DE becomes de-DE, en_US becomes en-US, ca stays ca. WordPress variant suffixes carry no BCP 47 meaning and are dropped, so de_DE_formal and de_CH_informal become de-DE and de-CH, and pt_PT_ao90 becomes pt-PT — a formal and an informal German page are the same language and region as far as a search engine is concerned.

Parameters
$locale : string

The WordPress locale (e.g. 'de_DE', 'de_DE_formal').

Tags
since
1.2.9
Return values
string —

The BCP 47 tag (e.g. 'de-DE').

jpkcom_simplelang_get_current_language()

Get current frontend language

jpkcom_simplelang_get_current_language() : string|null

Returns the currently active language for the frontend.

Tags
since
1.0.0
Return values
string|null —

The current language locale or null if using site default.

jpkcom_simplelang_get_site_default_locale()

Get site default locale

jpkcom_simplelang_get_site_default_locale() : string

Returns the site's default locale, ignoring any temporary locale switches. This is the locale set in Settings > General.

Tags
since
1.1.0
Return values
string —

The site default locale (e.g., 'de_DE', 'en_US').

jpkcom_simplelang_get_language_name()

Get language name from locale

jpkcom_simplelang_get_language_name(string $locale) : string

Converts a locale code to a human-readable language name.

Parameters
$locale : string

The locale code (e.g., 'de_DE', 'fr_FR').

Tags
since
1.1.0
Return values
string —

The language name in native language.

jpkcom_simplelang_group_posts_by_language()

Group posts by language

jpkcom_simplelang_group_posts_by_language(array<string, mixed> $query_args) : array<string, array<int, WP_Post>>

Queries posts and groups them by their assigned language for display in the translation links meta box.

Parameters
$query_args : array<string, mixed>

WP_Query arguments.

Tags
since
1.1.0
Return values
array<string, array<int, WP_Post>> —

Posts grouped by locale.

jpkcom_simplelang_validate_translations()

Validate translation links

jpkcom_simplelang_validate_translations(int $post_id, array<string|int, int> $translation_ids) : array<string|int, int>

Ensures that translation links are valid and prevents duplicate languages.

Parameters
$post_id : int

The current post ID.

$translation_ids : array<string|int, int>

Array of translation post IDs.

Tags
since
1.1.0
Return values
array<string|int, int> —

Validated array of translation post IDs.

jpkcom_simplelang_get_translation_posts()

Get translation posts efficiently

jpkcom_simplelang_get_translation_posts(array<string|int, int> $post_ids) : array<string|int, WP_Post>

Fetches multiple posts in a single query to avoid N+1 query problems.

Parameters
$post_ids : array<string|int, int>

Array of post IDs to fetch.

Tags
since
1.1.0
Return values
array<string|int, WP_Post> —

Array of post objects.

jpkcom_simplelang_sync_translations()

Sync translation links bidirectionally

jpkcom_simplelang_sync_translations(int $post_id, array<string|int, int> $new_translations) : void

Updates translation links for the current post and ensures all posts in the translation set are linked to each other. Creates a complete translation set where every post links to all others in the set.

Parameters
$post_id : int

The post ID to sync.

$new_translations : array<string|int, int>

Array of translation post IDs.

Tags
since
1.1.0

jpkcom_simplelang_render_translations_meta_box()

Render translation links meta box

jpkcom_simplelang_render_translations_meta_box(WP_Post $post) : void

Displays a multi-select dropdown with posts grouped by language.

Parameters
$post : WP_Post

Current post object.

Tags
since
1.1.0

jpkcom_simplelang_output_hreflang_tags()

Generate and output hreflang tags

jpkcom_simplelang_output_hreflang_tags(int $post_id, array<string|int, int> $translation_ids) : void

Creates hreflang link tags for all translations including the current post.

Parameters
$post_id : int

The current post ID.

$translation_ids : array<string|int, int>

Array of translation post IDs.

Tags
since
1.1.0

jpkcom_simplelang_render_meta_box()

Render language selection meta box

jpkcom_simplelang_render_meta_box(WP_Post $post) : void

Displays a dropdown with all available WordPress languages.

Parameters
$post : WP_Post

Current post object.

Tags
since
1.0.0

jpkcom_simplelang_is_valid_locale()

Check whether a locale may be stored as a post language

jpkcom_simplelang_is_valid_locale(string $locale) : bool

Validated against the locales WordPress actually has installed, plus en_US, which needs no language pack. That is the same list the meta box builds its options from, so anything offered can also be saved.

Up to 1.2.8 this was a regex, /^[a-z]{2,3}(_[A-Z]{2})?$/, which silently rejected every WordPress variant locale: de_DE_formal, nl_NL_formal, de_CH_informal, pt_PT_ao90 and art_xemoji. The meta box offered them, save_post dropped them, and nothing said so — this plugin even ships de_DE_formal translations of its own. A whitelist is both stricter (no invented locales) and complete (every real one).

Parameters
$locale : string

The locale to check.

Tags
since
1.2.9
Return values
bool —

True when the locale may be stored.

jpkcom_simplelang_get_post_language()

Get post language

jpkcom_simplelang_get_post_language([int|null $post_id = null ]) : string|null

Retrieves the language set for a specific post.

Parameters
$post_id : int|null = null

Optional. Post ID. Defaults to current post.

Tags
since
1.0.0
Return values
string|null —

The language locale or null if not set.

jpkcom_simplelang_get_oxygen_language_options()

Get language options for Oxygen Builder

jpkcom_simplelang_get_oxygen_language_options() : array<string, string>

Returns an array of available languages formatted for Oxygen Builder conditions.

Tags
since
1.0.0
Return values
array<string, string> —

Array of language codes and names.

jpkcom_simplelang_oxygen_post_language_is()

Oxygen condition callback: Post language is specific value

jpkcom_simplelang_oxygen_post_language_is(string $value, string $operator) : bool

Checks if the post has a specific language set.

Parameters
$value : string

The language code to check.

$operator : string

The comparison operator (== or !=).

Tags
since
1.0.0
Return values
bool —

True if the condition matches.

jpkcom_simplelang_oxygen_has_custom_language()

Oxygen condition callback: Post has custom language

jpkcom_simplelang_oxygen_has_custom_language(string $value, string $operator) : bool

Checks if the post has any custom language set (not using site default).

Parameters
$value : string

The value to check ('true' or 'false').

$operator : string

The comparison operator (always ==).

Tags
since
1.0.0
Return values
bool —

True if the condition matches.

jpkcom_simplelang_oxygen_uses_default_language()

Oxygen condition callback: Post uses default language

jpkcom_simplelang_oxygen_uses_default_language(string $value, string $operator) : bool

Checks if the post is using the site default language (no custom language set).

Parameters
$value : string

The value to check ('true' or 'false').

$operator : string

The comparison operator (always ==).

Tags
since
1.0.0
Return values
bool —

True if the condition matches.

On this page

Search results