Permissions & Roles

PerfLocale provides a comprehensive permissions system with a custom Translator role and granular capabilities that integrate with WordPress's built-in role system.

Custom Role: Translator

Slug: perflocale_translator

The Translator role is designed for team members who only need to translate content. They can edit posts and pages (to translate them) but cannot publish, delete, or manage site settings.

WordPress capabilities included:

Capability	Granted
read	Yes
edit_posts	Yes
edit_others_posts	Yes
edit_published_posts	Yes
edit_pages	Yes
edit_others_pages	Yes
edit_published_pages	Yes
upload_files	Yes
publish_posts	No
delete_posts	No
manage_options	No

Custom Capabilities

PerfLocale adds 9 custom capabilities that control access to specific plugin features.

Capability Matrix

Capability	Translator	Editor	Administrator	Description
perflocale_translate	Yes	Yes	Yes	Create and edit translations
perflocale_manage_translations	No	Yes	Yes	Manage translation settings, assign workflow
perflocale_manage_languages	No	No	Yes	Add, edit, delete languages
perflocale_manage_glossary	No	Yes	Yes	Add, edit, delete glossary terms
perflocale_manage_addons	No	No	Yes	Manage plugin addons
perflocale_use_mt	Yes	Yes	Yes	Use machine translation
perflocale_bulk_translate	No	Yes	Yes	Run bulk translation jobs
perflocale_import_export	No	No	Yes	Import/export translations (XLIFF, PO/MO)
perflocale_view_analytics	Yes	Yes	Yes	View translation analytics dashboard

Capability Details

perflocale_translate

The core translation capability. Users with this cap can:

• Create translation versions of posts, pages, and terms
• Edit existing translations
• See the Translations panel in the block/classic editor

perflocale_manage_translations

Management-level access:

• Assign translations to other users via the workflow system
• Change workflow statuses (assigned, in review, approved)
• Manage translation priorities and deadlines

perflocale_manage_languages

Administrative control over languages:

• Add new languages
• Edit language settings (name, locale, flag, direction)
• Delete languages
• Set the default language
• Reorder languages

perflocale_manage_glossary

Glossary management:

• Add glossary terms
• Edit existing terms
• Delete terms
• These terms are enforced during machine translation

perflocale_manage_addons

Addon lifecycle management:

• View the Addons page
• (Reserved for future manual addon install/uninstall)
• Currently addons auto-activate based on compatible plugins

perflocale_use_mt

Machine translation access:

• Trigger machine translation for individual posts
• Access the "MT" button in the editor sidebar
• Uses configured MT provider (DeepL, Google, Microsoft, LibreTranslate)

perflocale_bulk_translate

Batch operations:

• Start bulk translation jobs for entire post types
• Monitor bulk translation progress
• Cancel running bulk jobs

perflocale_import_export

Data portability:

• Export translations to XLIFF 2.0 format
• Import XLIFF files
• Export string translations to PO/MO files
• Migrate from WPML or Polylang

perflocale_view_analytics

Read-only analytics access:

• View the Analytics dashboard
• See translation progress by language
• View workflow summaries and system stats

Admin Menu Visibility

Menu Item	Required Capability
Dashboard	perflocale_translate
Languages	perflocale_manage_languages
Strings	perflocale_manage_translations
Glossary	perflocale_manage_glossary
Addons	perflocale_manage_addons
Analytics	perflocale_view_analytics
Settings	manage_options (WP core)

REST API Permissions

Endpoint	Required Check
GET /languages	Public by default (no auth required) - gateable via perflocale/api/languages_public filter
POST /languages	perflocale_manage_languages
PUT/DELETE /languages/{slug}	perflocale_manage_languages
GET /translations/{type}/{id}	perflocale_translate + edit_post
POST /translations/{type}/{id}	perflocale_translate + edit_post
PUT /translations/{type}/{id}/{lang}	perflocale_translate + edit_post
DELETE /translations/{type}/{id}/{lang}	perflocale_translate + delete_post
GET /strings	perflocale_translate
POST /strings/scan	manage_options
POST /machine-translate	perflocale_use_mt + edit_post
POST /import/*	perflocale_import_export
POST /xliff/*	perflocale_import_export
PUT /workflow/{id}/{lang_id}	perflocale_translate + edit_post
POST /webhooks	manage_options

Workflow States

Translations move through a workflow tracked in the wp_perflocale_workflow table:

Unassigned → Assigned → In Progress → In Review → Approved → Published

State	Who can set it	Description
unassigned	System	Default state for new translations
assigned	Editor, Admin	Translation assigned to a translator
in_progress	Translator	Translator has started working
review	Translator	Submitted for review
approved	Editor, Admin	Translation approved
published	Editor, Admin	Translation published on the site

Programmatic Usage

Check capabilities in PHP

use PerfLocale\Admin\TranslatorRole;

// Check a specific capability.
if ( TranslatorRole::current_user_can( 'perflocale_translate' ) ) {
	// User can translate.
}

// Or use WordPress core function.
if ( current_user_can( 'perflocale_manage_languages' ) ) {
	// User can manage languages.
}

Grant a capability to a custom role

$role = get_role( 'my_custom_role' );

if ( $role ) {
	$role->add_cap( 'perflocale_translate' );
	$role->add_cap( 'perflocale_use_mt' );
}

Remove all PerfLocale capabilities

On plugin deactivation, call:

PerfLocale\Admin\TranslatorRole::remove_roles();

This removes the Translator role and all custom capabilities from all roles.

Hooks

perflocale/roles/editor_caps

Filters the capabilities granted to the Editor role when the plugin activates. Return an empty array to prevent Editors from receiving any PerfLocale capabilities. Return a subset to restrict them to specific ones. The Administrator role is unaffected by this filter.

// Remove ALL PerfLocale capabilities from the Editor role.
add_filter( 'perflocale/roles/editor_caps', '__return_empty_array' );

// Grant only translation access to Editors (no bulk-translate, no glossary management).
add_filter( 'perflocale/roles/editor_caps', function ( array $caps ): array {
	return [
		'perflocale_translate'      => true,
		'perflocale_use_mt'         => true,
		'perflocale_view_analytics' => true,
	];
} );

Note: Capability grants are written to the database the first time the plugin activates (version-gated). If you add this filter to an existing install, reset the grant by running delete_option('perflocale_caps_version') in a one-time hook, then let WordPress reload - the filter will apply on the next admin_init.

perflocale/roles/cap_roles

Filters which WordPress roles have PerfLocale capabilities removed on plugin deactivation or uninstall. This filter fires in three places - TranslatorRole::remove_roles() (deactivation), and both the full-wipe and preserve-data branches of uninstall.php.

// Do NOT strip caps from the Editor role on deactivation / uninstall.
// Useful if you manage editor access separately and don't want it wiped.
add_filter( 'perflocale/roles/cap_roles', function ( array $roles ): array {
	return array_diff( $roles, [ 'editor' ] ); // keeps ['administrator']
} );

// Extend cleanup to a custom role that was granted caps programmatically.
add_filter( 'perflocale/roles/cap_roles', function ( array $roles ): array {
	$roles[] = 'shop_manager';
	return $roles;
} );

Workflow hooks

// Filter workflow assignment.
add_action( 'perflocale/workflow/assigned', function( $object_id, $type, $lang_id, $user_id ) {
	// Send notification email to the assigned translator.
}, 10, 4 );

// Filter workflow status changes.
add_action( 'perflocale/workflow/status_changed', function( $object_id, $type, $lang_id, $status ) {
	// Log status change or trigger automation.
}, 10, 4 );