Skip to content

Add lang attribute to <html> tag in page template#5811

Open
evnchn wants to merge 2 commits intozauberzeug:mainfrom
evnchn:html-lang-attribute
Open

Add lang attribute to <html> tag in page template#5811
evnchn wants to merge 2 commits intozauberzeug:mainfrom
evnchn:html-lang-attribute

Conversation

@evnchn
Copy link
Copy Markdown
Collaborator

@evnchn evnchn commented Feb 19, 2026

Motivation

The <html> tag in NiceGUI's page template lacks a lang attribute. This affects accessibility (screen readers) and SEO (search engines use it to determine page language).

Split out from #5767 per review feedback — this is a library-wide template change affecting all NiceGUI users.

Implementation

  • nicegui/templates/index.html: Changes <html> to <html lang="{{ language.split('-')[0] }}">, using the primary language subtag from the configured NiceGUI language (e.g. 'en' from 'en-US')

The language template variable is always populated via self.page.resolve_language() in Client.build_response(), so it is never None.

Progress

  • I chose a meaningful title that completes the sentence: "If applied, this PR will..."
  • The implementation is complete.
  • If this PR addresses a security issue, it has been coordinated via the security advisory process.
  • Pytests have been added (or are not necessary).
  • Documentation has been added (or is not necessary).

🤖 Generated with Claude Code

@evnchn @claude
Add lang attribute to <html> tag in page template
2e0a787 
Sets the HTML `lang` attribute based on the NiceGUI language setting,
improving accessibility and SEO. The language code is split on '-' to
use just the primary subtag (e.g. 'en' from 'en-US').

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@evnchn evnchn added the feature Type/scope: New or intentionally changed behavior label Feb 19, 2026
This was referenced Feb 19, 2026
Open
Closed
@falkoschindler falkoschindler added the review Status: PR is open and needs review label Feb 19, 2026
@falkoschindler falkoschindler self-requested a review February 19, 2026 09:57
falkoschindler
falkoschindler reviewed Feb 19, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@falkoschindler falkoschindler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @evnchn!
One concern about the current approach:

split('-')[0] discards meaningful region/script information for several languages in the Language type. For example:

  • zh-CN (Simplified Chinese) and zh-TW (Traditional Chinese) both become just zh - screen readers use the lang attribute to select the correct voice/pronunciation, and these variants are meaningfully different
  • pt-BR (Brazilian Portuguese) and pt (European Portuguese) both become pt

Almost all Quasar language codes are already valid BCP 47 tags. The simplest fix would be to pass the full value directly:

<html lang="{{ language }}">

This preserves zh-CN, pt-BR, ko-KR, etc. where the distinction matters for accessibility.

@falkoschindler falkoschindler added this to the 3.8 milestone Feb 19, 2026
evnchn
evnchn commented Feb 19, 2026
View reviewed changes
@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Feb 19, 2026

I agree with you.

@falkoschindler
Copy link
Copy Markdown
Contributor

falkoschindler commented Feb 19, 2026

One thing to consider: the language parameter primarily controls Quasar's UI components (date pickers, button labels, etc.) and defaults to en-US. Many developers may never have changed it, even if their app content is in another language.

Before this change, the <html> tag has no lang attribute, so browsers infer the page language from content (usually correctly). After this change, every NiceGUI app that didn't explicitly set language would declare lang="en" — which tells browsers to stop guessing and trust the declared value. This affects spell checking (wrong dictionary for inputs), screen readers (wrong voice/pronunciation), and CSS hyphens: auto (wrong hyphenation rules).

So for a developer with e.g. a German-language app who never touched the language setting, this change would actively tell browsers "this page is English," which could be worse than the current behavior of saying nothing.

Could this be made opt-in instead (e.g. only emit lang when the user explicitly sets it), or is the expectation that developers should always configure language to match their content?

@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Feb 19, 2026

Hmm fair. Not only that, considering cases where the user doesn't know what the language is (perhaps user-provided content dominates), the possibility of language=None will persist into future NiceGUI versions, not just a stopgap until 4.0

@falkoschindler falkoschindler added analysis Status: Requires team/community input and removed review Status: PR is open and needs review labels Feb 19, 2026
@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Feb 19, 2026

@falkoschindler do you think evnchn#85 is ready to be brought upstream?

@falkoschindler
Copy link
Copy Markdown
Contributor

falkoschindler commented Feb 19, 2026

@evnchn Looks like you closed evnchn#85 already.
Let's postpone this discussion to 3.10 to focus on 3.8.

@falkoschindler falkoschindler modified the milestones: 3.8, 3.10 Feb 19, 2026
@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Feb 19, 2026

@falkoschindler I closed it to bake stuff into 1 commit and ask Claude Code to review (as usual)

It is alive at https://github.com/evnchn/nicegui/tree/copilot/add-lang-attribute-html, but sure let's focus on 3.8 first.

@evnchn evnchn mentioned this pull request Mar 29, 2026
Draft
@evnchn
Copy link
Copy Markdown
Collaborator Author

evnchn commented Mar 29, 2026

We have agreed to tackle i18n not in 3.10. I'm not sure if it will be 3.11 though (since if further work is required for the NiceGUI docs design, doing the i18n later dodges merge conflicts)

@evnchn evnchn modified the milestones: 3.10, Next Mar 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@falkoschindler falkoschindler falkoschindler left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

analysis Status: Requires team/community input feature Type/scope: New or intentionally changed behavior

Projects

None yet

Milestone

Next

Development

Successfully merging this pull request may close these issues.

2 participants

@evnchn @falkoschindler