feat(map): display OpenHistoricalMap labels in user's preferred language by mahula · Pull Request #1056 · gramps-project/gramps-web

mahula · 2026-04-08T08:44:25Z

Motivation

OpenHistoricalMap (OHM) displays map labels in the default local contemporary language by default. Users expect map labels to appear in their preferred language matching the application's frontend language setting, as requested in issue #493 and the related forum topic.

Since OHM serves vector tiles, it supports on-the-fly language switching via the ?language=<ISO-639-code> URL parameter (see openhistoricalmap-embed#8). This PR implements that mechanism.

Changes

Problem: Locale code mismatch

Frontend locales use regional variants (e.g., de_AT, en_GB, pt_BR) while OpenHistoricalMap only supports base ISO 639-1 codes (de, en, pt). Without normalization, users with de_AT locale would not get German labels as OHM wouldn't recognize the code.

Solution

Added OHM_LOCALE_MAP in src/util.js — maps all frontend locales to their OHM-compatible base codes:
- de_AT → de, en_GB → en, pt_BR → pt, etc.
- Base codes map to themselves unchanged
Added normalizeOhmLocale() in src/util.js — converts frontend locale codes to OHM-compatible codes with explicit fallback chain:
- Returns mapped value if found in OHM_LOCALE_MAP
- Falls back to extracting base code (split('_')[0])
- Falls back to 'en' for null/undefined/empty/unknown
Modified _getStyleUrl() in src/components/GrampsjsMap.js:
- When OHM layer is selected, appends ?language=<locale> to the style URL

How to Test

Manual Testing

Set browser language to a specific locale (e.g., German de-AT in browser settings)
Navigate to the Map view

Select "Historical Map" layer from the layer switcher

OpenHistoricalMap: requesting labels in locale "de" (frontend locale: "de_AT")

Verify map labels appear in German (not the default local contemporary names)

Supported Locales

The feature works with all frontend locales. Key regional variants that normalize correctly:

de_AT, de_DE → German labels
en_GB, en_US → English labels
pt_BR, pt_PT → Portuguese labels
zh_CN, zh_HK, zh_TW → Chinese labels

Fallback Behavior

If a locale is not supported by OHM (e.g., a future locale not in the map), it falls back to the base code. If no base code is available, defaults to English.

Unit Tests

Run the new test suite:

npm test -- test/unit/mapOhmLocale.test.js

Tests cover:

Base language code mapping (de → de)
Regional variant normalization (de_AT → de)
Fallback for undefined, null, empty string
Unknown locale handling with base code extraction
Edge cases (multiple underscores, locales not in map)

Files Changed

src/components/GrampsjsMap.js — added language parameter to OHM style URL
src/util.js — added OHM_LOCALE_MAP and normalizeOhmLocale()
test/unit/mapOhmLocale.test.js — new comprehensive test suite

Related Issue

Fixes #493

When the OpenHistoricalMap layer is selected, append the language parameter (?language=<locale>) to the style URL so that map labels are displayed in the user's preferred language matching the frontend locale setting. Fixes gramps-project#493

- Add OHM_LOCALE_MAP in util.js for mapping frontend locales (de_AT, en_GB, pt_BR, etc.) to OpenHistoricalMap-compatible ISO 639-1 codes (de, en, pt) - Add normalizeOhmLocale() function with explicit fallback chain - Add debug logging when OHM style is requested showing the locale mapping - Add comprehensive unit tests covering: - Base language code mapping - Regional variant normalization - Fallback behavior for undefined/null/empty/unknown locales - OHM_LOCALE_MAP completeness validation Fixes gramps-project#493

DavidMStraub · 2026-04-08T09:16:14Z

Thanks for looking into this! Great if it's that simple 🙂

Copilot

Pull request overview

Adds OpenHistoricalMap (OHM) label-language selection so the historical map layer’s labels align with the app’s current frontend locale, addressing issue #493.

Changes:

Introduces OHM_LOCALE_MAP and normalizeOhmLocale() to normalize frontend locales (e.g., de_AT) to OHM-compatible base codes (e.g., de).
Updates GrampsjsMap to append ?language=<code> when selecting the OHM style.
Adds unit tests covering locale normalization and mapping completeness.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
`src/components/GrampsjsMap.js`	Appends an OHM `language` query parameter based on current frontend language.
`src/util.js`	Adds locale mapping constant and normalization helper for OHM language codes.
`test/unit/mapOhmLocale.test.js`	Adds tests for locale normalization behavior and mapping coverage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Use URL.searchParams.set() instead of string interpolation to properly handle OHM style URLs that may already contain query parameters. Fixes potential issue noted in PR review.

…uplicating Removes hardcoded frontendLanguages list from test file to avoid maintenance duplication. Now imports from src/strings.js directly.

@param

Clarify the actual fallback chain in the JSDoc comment: 1. Falsy locale → 'en' 2. In OHM_LOCALE_MAP → use mapped value 3. Unknown locale with base code → extract base code 4. No base code available → 'en' Also add null to @param type since function handles it in practice.

DavidMStraub · 2026-04-08T10:26:05Z

Can you please close the comments once you address them with a reply what you did about them, so I don't have to dig through everything myself once more, thanks

mahula · 2026-04-08T10:45:26Z

Can you please close the comments once you address them with a reply what you did about them, so I don't have to dig through everything myself once more, thanks

The Copilit comments are commented with the commit references.
Another proper way to re-review thhe pull request after changes made required by a reviewer, could be, asking Copilot to review the updated pull request again.

DavidMStraub · 2026-04-08T10:57:17Z

Thanks!

asking Copilot to review the updated pull request again.

I know, but using this a lot recently (sometimes getting 3 or 4 copilot reviews on my own PRs) I know it's often quite random whether it picks up its previous commit and related changes or not. So better to have a human confirm it.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

1ec5 · 2026-04-08T14:39:37Z

Oh hey, I didn’t realize you were working on this, glad to see it. In case you’re interested, I’m working on a new Diplomat plugin for localizing any MapLibre style. It’s a lot more thorough than what either of us have implemented for OHM so far. OpenHistoricalMap/openhistoricalmap-embed#39 would migrate to that plugin. Unfortunately it’s held up by a pesky font issue in the stylesheet, but only because I was looking to use Diplomat’s dual language labeling feature. If you don’t enable that, then it works just fine.

mahula · 2026-04-08T14:47:17Z

In case you’re interested, I’m working on a new Diplomat plugin for localizing any MapLibre style. It’s a lot more thorough than what either of us have implemented for OHM so far. OpenHistoricalMap/openhistoricalmap-embed#39 would migrate to that plugin.

That sounds great.
What do you think about - when the plugin is ready - opening a pull request using it to replace the current solution?

Unfortunately it’s held up by a pesky font issue in the stylesheet, but only because I was looking to use Diplomat’s dual language labeling feature. If you don’t enable that, then it works just fine.

Even if off-topic here, if there is an issue about the font related blockage, I would offer support with reviewing end maybe helping to test or fix it.

1ec5 · 2026-04-09T05:56:25Z

Diplomat is more or less ready to use. I’m just waiting for some feedback about the API design before releasing a v1.0.

The font issue is OpenHistoricalMap/issues#1258. The fix might just be to drop the remote fonts from the stylesheet altogether.

DavidMStraub · 2026-04-09T06:52:45Z

That sounds great! I think it might be better then to directly implement this rather than the partial solution in this PR.

DavidMStraub · 2026-04-10T09:47:30Z

That sounds great! I think it might be better then to directly implement this rather than the partial solution in this PR.

Forgot that I merged this already 😆 so let's ship the workaround and then switch to the better solution in the next release.

…ed language (#1056)" This reverts commit 86f3402.

DavidMStraub · 2026-04-10T10:04:31Z

I had to revert the change because it had no effect whatsoever - the query argument is ignored by OHM.

@mahula did you test this locally?

mahula · 2026-04-10T11:54:27Z

I had to revert the change because it had no effect whatsoever - the query argument is ignored by OHM.

@mahula did you test this locally?

Not thoroughly enough.

The Diplomat plugin will be the proper solution for the issue #493

mahula added 2 commits April 8, 2026 09:43

DavidMStraub reviewed Apr 8, 2026

View reviewed changes

Comment thread src/components/GrampsjsMap.js Outdated

DavidMStraub self-requested a review April 8, 2026 09:16

remove debug logging from GrampsjsMap._getStyleUrl()

ee15747

DavidMStraub requested review from Copilot and removed request for DavidMStraub April 8, 2026 09:35

Copilot started reviewing on behalf of DavidMStraub April 8, 2026 09:36 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

Comment thread src/components/GrampsjsMap.js Outdated

Comment thread src/components/GrampsjsMap.js

Comment thread src/util.js

Comment thread test/unit/mapOhmLocale.test.js Outdated

Comment thread src/components/GrampsjsMap.js

mahula added 3 commits April 8, 2026 11:53

refactor(map): use URL API for OHM style URL construction

5500207

Use URL.searchParams.set() instead of string interpolation to properly handle OHM style URLs that may already contain query parameters. Fixes potential issue noted in PR review.

refactor(test): import frontendLanguages from strings.js instead of d…

3e60250

…uplicating Removes hardcoded frontendLanguages list from test file to avoid maintenance duplication. Now imports from src/strings.js directly.

mahula mentioned this pull request Apr 8, 2026

Dynamically update OpenHistoricalMap language when UI language changes #1057

Open

mahula requested a review from DavidMStraub April 8, 2026 10:22

DavidMStraub requested a review from Copilot April 8, 2026 10:57

Copilot started reviewing on behalf of DavidMStraub April 8, 2026 10:58 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

DavidMStraub approved these changes Apr 8, 2026

View reviewed changes

DavidMStraub merged commit 86f3402 into gramps-project:main Apr 8, 2026
5 checks passed

mahula deleted the feature/ohm-language-labels branch April 8, 2026 11:24

DavidMStraub added a commit that referenced this pull request Apr 10, 2026

Revert "feat(map): display OpenHistoricalMap labels in user's preferr…

f9d188c

…ed language (#1056)" This reverts commit 86f3402.

mahula mentioned this pull request Apr 10, 2026

OpenHistoricalMap labels should be in the preferred language #493

Closed

Conversation

mahula commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Problem: Locale code mismatch

Solution

How to Test

Manual Testing

Supported Locales

Fallback Behavior

Unit Tests

Files Changed

Related Issue

Uh oh!

Uh oh!

DavidMStraub commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DavidMStraub commented Apr 8, 2026

Uh oh!

mahula commented Apr 8, 2026

Uh oh!

DavidMStraub commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

1ec5 commented Apr 8, 2026

Uh oh!

mahula commented Apr 8, 2026

Uh oh!

1ec5 commented Apr 9, 2026

Uh oh!

DavidMStraub commented Apr 9, 2026

Uh oh!

DavidMStraub commented Apr 10, 2026

Uh oh!

DavidMStraub commented Apr 10, 2026

Uh oh!

mahula commented Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mahula commented Apr 8, 2026 •

edited

Loading