Technical solution to set Grafana language dynamically

This document outlines the methods to configure or change the Grafana interface language, based on user preferences, and Grafana's built-in internationalization (i18n) features.

Ways to Set or Change the Language in Grafana

1. Using Browser-Based Translation Extensions

   1. Browser tools (e.g., Google Translate extension) can translate the Grafana UI on-the-fly.

2. Hardcoded Language in Dashboards.

   1. This involves manually hardcoding translated titles, descriptions, and labels in specific languages during the time of dashboard creation.

3. Using EF Agent Desk's Built-in Translation API. Recommended

   1. This allows dynamic rendering of dashboard elements (titles, descriptions, etc.) based on the user’s selected language on the Agent DEsk.

4. Grafana built-in language support.

Translated areas supported by Grafana's built-in Language Support.

1. Navigation and sidebar

   1. Menu items: Dashboards, Explore, Alerts, Configuration, etc.

   2. Tooltips and system buttons

2. Dashboard Interface

   1. Common actions: Save, Share, Edit, Settings

   2. Panel menus and header actions

   3. Time picker and auto-refresh controls

3. User Preferences & Profile

   1. Language selector option in user profile

   2. Date/time format and theme settings

4. Settings Pages

   1. Organization and user settings

   2. Plugin installation/configuration screens

   3. Team and role management

5. Alerts & Notification Channels

   1. UI labels, status indicators, and configuration actions

6. Authentication UI

   1. Login, registration, and password reset screens

   2. Field labels and error messages

List of Built-in languages supported in Grafana v10.3.2+

1. English  

2. French     

3. German  

4. Spanish  

5. Portuguese 

6. Simplified Chinese 

7. Traditional Chinese 

8. Japanese   

9. Korean  

10. Russian   

11. Turkish   

12. Ukrainian   

13. Polish    

Procedure to implement language translation by using AgentDesks translation API.

This procedure outlines how to dynamically apply language translations in Grafana dashboards by leveraging the Agent Desk Translation API.

1. Add a Language Selection Variable in Grafana

   1. Define a new dashboard constant variable ie language_format_prefix.
      

      

      1. This variable will store the language code (e.g., en, ar, fr) passed from the Agent Desk when user switches to any language preference.

      2. It will be passed by the frontend to Grafana via Grafana’s embedded URL. eg

      3. <GRAFANA_BASE_URL>&language_format_prefix=ar
         

2. Connect to the Translation API

   1. Create a variable that will store the dynamic translated value.

      1. eg. For queue_summary_stats_panel_title you need to define a variable.
         

         

      2. On the path , add API Endpoint to get the translated descripitions:

      3. <FQDN>/assets/i18n/{language_format_prefix}.json
         

      4. Grafana will make a HTTP (Agent Desk Translation API) to fetch the translated info based on the language code passed to Grafana via embedded URL.
         Example for Arabic. when language_format_prefix variable is set to ar

      5. <FQDN>/assets/i18n/ar.json
         

   2. Based on the HTTP response, extract queue_summary_stats_panel_title response and store it in the variable defined at step(2a(i)).

      1. Translation API Response Format for Arabic lang

      2. JavaScript

         {
           "queue_summary_stats_title": "نشط مع الوكلاء",
           "queue_summary_stats_description": "عنوان ملخص إحصائيات الطابور",
           "bot_stats_title": "عنوان إحصائيات الروبوت",
           "bot_stats_summary_description": "وصف ملخص إحصائيات الروبوت"
         }
         

   3. This will be the translated response and you can use the queue_summary_stats_panel_title in your panel to display the translated response.

      

   4. Use the translated variables from the response and set them to a dynamic variable, so Grafana will automatically replace the translated fields based on the translated value.
      Example.

   

Limitations

With the implementation of using the i18n API exposed by the Agent Desk, there are some limitations to some content that we cannot translate on the grafana dashboard.

1. Dashboard folder name and file name

   

2. Dropdown variables label name
   - Name / Label, are static text used for UI display in the dashboard variable. Only the value of the variable can be dynamicaly translated.

   

3. Error message from API