feat(core): add locale and no-translate attributes to html element on startup (#16966)

Alexander-Taran · web-flow · commit 7751b60a9808 · 2026-02-18T18:05:32.000+01:00
- Set 'lang' attribute based on detected locale.
- Prevent auto-translation by setting 'translate="no"' and adding
  '.notranslate' class.

This ensures better i18n support and avoids issues with unintended UI
translation.

Signed-off-by: Alexander Taran &lt;a.taran@outlook.com&gt;
diff --git a/packages/core/src/browser/common-frontend-contribution.ts b/packages/core/src/browser/common-frontend-contribution.ts
@@ -291,10 +291,16 @@ export class CommonFrontendContribution implements FrontendApplicationContributi
     }
 
     onStart(): void {
+        this.setupHtmlLanguageAttributes(document.documentElement);
         this.storageService.getData<{ recent: Command[] }>(RECENT_COMMANDS_STORAGE_KEY, { recent: [] })
             .then(tasks => this.commandRegistry.recent = tasks.recent);
     }
 
+    protected setupHtmlLanguageAttributes(element: HTMLElement): void {
+        nls.setHtmlLang(element);
+        nls.setHtmlNoTranslate(element);
+    }
+
     onStop(): void {
         const recent = this.commandRegistry.recent;
         this.storageService.setData<{ recent: Command[] }>(RECENT_COMMANDS_STORAGE_KEY, { recent });
diff --git a/packages/core/src/browser/secondary-window-handler.ts b/packages/core/src/browser/secondary-window-handler.ts
@@ -23,6 +23,7 @@ import { Emitter } from '../common/event';
 import { isSecondaryWindow, SecondaryWindowRootWidget, SecondaryWindowService } from './window/secondary-window-service';
 import { KeybindingRegistry } from './keybinding';
 import { MAIN_AREA_ID, TheiaDockPanel } from './shell/theia-dock-panel';
+import { nls } from '../common/nls';
 
 /** Widgets to be contained inside a DockPanel in the secondary window. */
 class SecondaryWindowDockPanelWidget extends SecondaryWindowRootWidget {
@@ -180,6 +181,8 @@ export class SecondaryWindowHandler {
             // See https://html.spec.whatwg.org/multipage/dom.html#document.title
             newWindow.document.title = `${widget.title.label} — ${mainWindowTitle}`;
 
+            this.setupHtmlLanguageAttributes(newWindow.document.documentElement);
+
             const element = newWindow.document.getElementById('widget-host');
             if (!element) {
                 console.error('Could not find dom element to attach to in secondary window');
@@ -218,6 +221,11 @@ export class SecondaryWindowHandler {
         });
     }
 
+    protected setupHtmlLanguageAttributes(element: HTMLElement): void {
+        nls.setHtmlLang(element);
+        nls.setHtmlNoTranslate(element);
+    }
+
     private onWidgetRemove(widget: Widget, newWindow: Window, rootWidget: SecondaryWindowRootWidget): void {
         // Close the window if the widget is disposed, e.g. by a command closing all widgets.
         this.onWillRemoveWidgetEmitter.fire([widget, newWindow]);
diff --git a/packages/core/src/common/nls.ts b/packages/core/src/common/nls.ts
@@ -68,6 +68,31 @@ export namespace nls {
     export function setLocale(id: string): void {
         window.localStorage.setItem(localeId, id);
     }
+
+    /**
+     * Sets the 'lang' attribute on the given HTML element based on the current locale.
+     * If no locale is set, defaults to 'en' (English).
+     * Typically used with document.documentElement (the <html> tag) to set the page language.
+     *
+     * @param element The HTML element to set the language attribute on
+     */
+    export function setHtmlLang(element: HTMLElement): void {
+        const lang = locale?.split('_').at(0) || 'en';
+        element.setAttribute('lang', lang);
+    }
+
+    /**
+     * Sets the 'translate' attribute to 'no' and adds the 'notranslate' class
+     * to the given HTML element. This prevents translation tools from translating
+     * the content of the element.
+     * Typically used with document.documentElement (the <html> tag) to disable page translation.
+     *
+     * @param element The HTML element to set translation attributes on
+     */
+    export function setHtmlNoTranslate(element: HTMLElement): void {
+        element.setAttribute('translate', 'no');
+        element.classList.add('notranslate');
+    }
 }
 
 interface NlsKeys {
