Find a translation key with verbose localization

[Discourse]

This documentation explains how to use verbose localization to find translation keys for custom text in Discourse.

Required user level: Administrator

Finding a translation key using verbose localization

Verbose localization is a powerful tool in Discourse that helps administrators find translation keys for custom text more effectively. This is particularly useful when you need to translate text appearing in multiple places in the Discourse UI.

Summary

This guide covers:

• Enabling verbose localization.
• Using verbose localization to identify translation keys.
• Practical applications and common use cases.

Enabling verbose localization

There are several ways to enable verbose localization, depending on your setup.

Using the Developer Toolbar (recommended)

The Discourse Developer Toolbar includes a built-in toggle for verbose localization. This is the easiest method and works on both self-hosted and hosted sites.

1. Open your browser’s developer console on your Discourse site.
2. Run:

   enableDevTools()
   

3. The page will reload and a developer toolbar will appear on the left side of the screen.
4. Click the (scroll) icon in the toolbar to toggle verbose localization on.
5. The page will reload with verbose localization enabled.

The developer toolbar state is stored in your browser’s local storage, and verbose localization state is stored in session storage. Other users will not be affected.

Using the browser console directly

1. Open your browser’s web inspector on your Discourse site.
2. Go to the console tab.
3. Enter the following JavaScript command at the prompt:

   I18n.enableVerboseLocalizationSession()
   

4. You should see a response similar to:
   
   

This session-specific approach ensures that other users won’t see translation markers when visiting the site.

Using the rails console (self-hosted only)

The verbose_localization site setting exists but is a hidden site setting. It cannot be found in the admin UI under “All Site Settings”. To enable it globally for all users on a self-hosted instance:

1. Access the rails console.
2. Run:

   SiteSetting.verbose_localization = true
   

This enables verbose localization for all users on the site. Prefer the session-based methods above to avoid cluttering the UI for other users.

Using verbose localization to find a translation key

When verbose localization is enabled, you’ll see numbers displayed after all customizable text on your site.

Steps to identify a translation key

1. Browse to the area containing the text you want to update. For example, if you’re looking to change the word “Name”:
   
   
2. Look for the associated translation number in your browser’s console:
   
   
3. Note the identified translation key, such as user.name.title.
4. Go to the Admin sidebar and enter site texts into the Search bar
5. Enter the translation key into the search box:
   
   
6. Click the text’s Edit button and update the text as needed.

Best practices

• Use session-specific verbose localization to avoid cluttering the UI for other users during translation tasks.
• Document frequently used translation keys for future reference.
• Regularly check for updates in the Discourse documentation to stay informed about new localization features.

Common issues and solutions

Issue: Translation markers visible to all users

Solution: Ensure you enable verbose localization exclusively for your session if other users shouldn’t see it. Use the Developer Toolbar or the I18n.enableVerboseLocalizationSession() console method instead of the global site setting.

Issue: Difficulty in finding correct translation key

Solution: Use the console and verbose localization markers accurately, and cross-reference the Customize Site Texts page.

FAQs

Q: Can verbose localization be restricted to admin or staff?
A: Verbose localization numbers can be hidden from non-technical users by enabling it in individual sessions via the Developer Toolbar or the browser console.

Q: How can string translations be verified?
A: After identifying and updating the translation key, review the UI changes in a new browser session or tab.

Additional resources

• Customize text in Discourse
• How to translate customized text content?
• Introducing Discourse developer toolbar

Last edited by @Moin 2024-07-22T10:35:10Z

Check document

Perform check on document:

[Moin]

@Discourse

Enabling the setting for all users

1. Navigate to your site settings page
   a. Go to the admin sidebar
   b. Select All Site Settings
   b. Enter verbose in the filter field of the settings page
2. Enable the verbose localization site setting.

The setting is now a hidden site setting, so you will no longer find it in “all site settings”

config/site_settings.yml

So you now need access to the rails console.

[benjamincfarmer (Ben Farmer)]

How should hosted systems now access this property?

[Lilly]

@benjamincfarmer

How should hosted systems now access this property?

like this

@Discourse

Enabling the setting for an individual session

or you can use the dev tools

@david

Verbose localization

Toggles the verbose localization feature