Configuring Role-Based Scanning

Role-based scanning solves one specific problem: a page shows different content to different users. By default Omnalingo scans as a visitor (unauthenticated) and as an administrator. If your site has content that only specific roles can see — membership tiers, shop manager controls, subscriber-only sections — you need to add those roles to the scan configuration.

When to Configure Additional Roles

Add scan roles when a customer reports:

• Strings not found during scan — content exists on the page but does not appear in the Dashboard after scanning
• Translation missing for logged-in users — a translated page shows English for a specific user but not for others
• Admin bar strings not translated — this is covered by the default administrator scan, so if admin bar strings are missing, the administrator scan may not be running

Do not add roles just because they exist on the site. Each additional role multiplies the number of HTTP requests during scanning. For a 1,000-page site:

• 2 roles (visitor + administrator): 2,000 scan requests
• 5 roles: 5,000 scan requests

Only add roles that genuinely render different translatable content.

How Authenticated Scanning Works

Omnalingo uses two different authentication methods depending on the scan type.

Visitor Scans (HMAC Token)

Visitor scans must be unauthenticated — no WordPress session. The request is authenticated via an HMAC token:

• Generated with SHA-256 using a site-specific secret key
• Includes a timestamp
• Has a 60-second TTL (time to live)
• Passed as a query parameter on the scan request URL

ScannerSubscriber validates the token on the receiving end. If the token is missing, expired, or invalid, the request is treated as a normal page view — no scan data is captured, no error is returned.

Role-Based Scans (Nonce-Based)

For administrator, editor, and custom role scans, Omnalingo creates an authenticated WordPress session for an existing user with the target role. The scan request includes a WordPress nonce for verification.

Important: Omnalingo does not create new users. It uses an existing user with the configured role. If no user with the required role exists on the site, that role’s scan is silently skipped.

Verification — check that a user exists for each configured role:

SELECT u.user_login, m.meta_value AS capabilities
FROM wp_users u
JOIN wp_usermeta m ON u.ID = m.user_id
WHERE m.meta_key = 'wp_capabilities'
AND m.meta_value LIKE '%shop_manager%';

Replace shop_manager with the target role name. If no row is returned, the role scan will be skipped.

Configuring Scan Roles

1. Open Advanced Settings

   Go to wp-admin → Omnalingo → Settings → Advanced.

2. Find the Scan Roles setting

   The setting is a multi-select field listing all WordPress roles registered on the site. Visitor is always included and cannot be removed.

3. Add the required roles

   Common additions:

   • shop_manager — WooCommerce shop manager controls, stock notices on product pages
   • customer — WooCommerce account page, order history, subscription information
   • subscriber — comment forms visible to logged-in users, membership content
   • Custom membership roles (e.g., gold_member, premium_subscriber)

4. Save Settings

5. Run a full rescan

   Go to Omnalingo → Dashboard → Scan Content. New role scans are processed in the same background queue as visitor scans. Wait for the scan to complete before checking results.

How Role-Tagged Strings Are Served

When a string is discovered during scanning, the role column in wp_omnalingo_url_strings records which role found it. This is visible directly:

SELECT s.original_string, us.role
FROM wp_omnalingo_strings s
JOIN wp_omnalingo_url_strings us ON s.id = us.string_id
JOIN wp_omnalingo_urls u ON us.url_id = u.id
WHERE u.url = '/about/'
ORDER BY us.role;

Strings discovered by the administrator scan (such as the WordPress admin bar) are served only to users with appropriate permissions. Strings discovered by the visitor scan are served to everyone. This prevents admin-only strings from showing in translated form on the public-facing site.

Diagnosing Incomplete Role Scans

Role scan silently skipped

If after adding a role and rescanning you still see no strings from that role:

1. Confirm a user with that role exists (SQL above)

2. Check whether the role was actually added to scan_roles in the database:

   SELECT option_value FROM wp_options WHERE option_name = 'omnalingo_options';

   Find scan_roles in the JSON output. It should be an array of role slugs, e.g., ["administrator", "shop_manager"].

3. Check the plugin log for errors during scan request dispatch:

   wp-content/omnalingo/logs/error.log

   Look for [WARNING] or [ERROR] entries with the role name.

Draft and private content not being scanned

Pages with draft, pending, future, or private post status return 404 to unauthenticated visitors. These statuses are defined in ScanQueueService as NON_PUBLIC_STATUSES. Scanning them requires an authenticated role (typically administrator). If draft content is missing from the translation index, confirm the administrator role is in scan_roles.

SELECT p.post_title, p.post_status
FROM wp_posts p
WHERE p.post_status IN ('draft', 'pending', 'private', 'future')
AND p.post_type = 'post';

If this returns posts that should be translated, ensure administrator is in scan_roles and rescan.

WooCommerce shop manager content missing

WooCommerce may show additional controls on product pages for shop managers (stock status, quick-edit links, admin notices). To confirm the shop_manager role sees different content:

1. Log in as a shop manager user.
2. Visit a product page.
3. Right-click → View Page Source.
4. Look for text strings that are not present in the source for a logged-out visitor.

If unique strings exist for the shop manager role, add shop_manager to scan_roles and rescan.

Performance Considerations

Each scan role runs as a separate pass over every URL in the index. For large sites:

URLs	Roles	Scan requests
500	2 (default)	1,000
500	4	2,000
5,000	4	20,000

Scan requests are processed via Action Scheduler in batches. For very large sites with many roles, schedule full rescans during low-traffic periods to avoid impacting site performance.

The Work-While-Polling mechanism on the Dashboard — where each status poll also processes a scan batch — is especially useful for large multi-role scans. Keep the Dashboard tab open during the operation.

Note

The omnalingo_translator role (Omnalingo’s custom translator user role) does not need to be added to scan roles. Translators see the same public content as visitors. The translator role exists for access control to the visual editor, not for content visibility.

Related Pages

• Scanning — Full technical detail on how the scan pipeline works
• Scan Not Working — Diagnostic steps when scanning produces no results
• WooCommerce Integration — WooCommerce-specific scanning considerations