Multilingual Breadcrumbs in SharePoint Online

SPFx Technical Deep Dive

SharePoint Online's native multilingual pages feature solves translation for the things you'd expect it to solve, it provides a translated page linked to the default language page, and there is a language switcher that moves a visitor between versions of the same page, term store labels carry their own translations natively, which is what powers the multilingual filters and refiners on this site's search pages.

Folders sit outside both of these mechanisms entirely. A folder in the Site Pages library has exactly one name, and that name is fixed the moment it's created. There is no native SharePoint concept of a "French folder name." If your breadcrumb navigation shows the folder a page lives in, and your site serves both English and French visitors, that single folder name is what everyone sees, regardless of which language they're reading the page in.

This is the gap the breadcrumb component closes.

Why this lives in the header webpart, not a standalone extension

The breadcrumb isn't a separate SPFx component. It's built directly into PageHeader, the same web part responsible for the site's branded header, background image, and search box.

This was a deliberate placement decision rather than a default. A breadcrumb has no reason to exist independently of the page chrome it sits inside, it needs to know the current page's URL, the site collection context, and it needs to render in a fixed, predictable position relative to the rest of the header. Building it as a child component inside PageHeader means it shares that context automatically, rather than duplicating context-resolution logic across two separate web parts, or relying on some other mechanism to keep two independently-placed components in sync with each other.

Practically, this also means the breadcrumb only appears wherever PageHeader itself is placed, which for this site is every content page. Adding it to a new page is a byproduct of adding the header, not a separate step.

What the breadcrumb actually shows

Two levels, always: the immediate parent folder, and the current page. Not a full path back to the site root, not every intermediate folder in a deep hierarchy, just enough for a visitor to understand where they are and one click back to where they came from.

The parent folder is rendered as a clickable link. The current page is plain text — standard breadcrumb convention, you don't link to the page a visitor is already on.

The two translation mechanisms, and why they're different

Pages translate themselves. The current page's label is read directly from that page's own native Title field, the same field SharePoint's Translate action populates when you create a language version of a page. This means pages require zero ongoing maintenance from a breadcrumb perspective — translate the page the normal way, and its breadcrumb label is automatically correct in whichever language a visitor is viewing.

Folders are translated via a SharePoint list, called BreadcrumbTranslations. Since folders have no native translation mechanism, this list is the source of truth for what a folder should be called in each supported language, and where its clickable link should actually go.

The list schema:

Column	Purpose
FolderName	The folder's actual name as it appears in the URL, the lookup key
LabelEN	English display label
LabelFR	French display label
FolderPath	URL of the English landing page representing this folder
FolderPathFR	URL of the French landing page representing this folder

Each folder that should appear as a clickable breadcrumb link needs exactly one row. The label columns control what text displays; the path columns control where the link goes, in each respective language.

Why a folder needs a landing page at all

A folder itself isn't a page, it's a container. Clicking a breadcrumb crumb that points at a bare folder path lands a visitor on SharePoint's default file-browse view of that folder's contents — a list of files, not a piece of readable content. That's rarely what you want a navigation click to do.

So every folder that appears in a breadcrumb is paired with an actual landing page, a real .aspx page representing that section, existing in both English and French via the native Translate action, same as any other page. The list's FolderPath and FolderPathFR columns point at these landing pages directly, not at the folder itself.

This means a folder genuinely serving as a breadcrumb destination is doing double duty: it's a physical container in the site structure, and conceptually, it's represented by a page that gives a visitor somewhere real to land.

How the language switch actually works

The breadcrumb's language is driven by the same mechanism that drives the rest of this site's multilingual chrome: the Locale query string parameter, e.g. ?Locale=fr-FR.

The breadcrumb doesn't infer language from the folder structure — the folder name in a URL is always the same regardless of which language version of a page you're viewing, since folder names themselves are never translated. Instead, the component reads the visitor's active locale directly, and uses it to decide which column to read: LabelEN and FolderPath when the locale isn't French, LabelFR and FolderPathFR when it is.

Concretely: without Locale=fr-FR present, a visitor sees the English label and the English landing page link, even on a page that itself happens to be the French translation. With Locale=fr-FR present, the French label and French link resolve instead. The folder side of the breadcrumb reflects the visitor's chosen language, not the physical page they happen to be looking at, which is the only sensible source of truth available, given folder names carry no language information of their own.

What this means in practice for content owners

Every new folder that should appear as a clickable, translated breadcrumb destination needs three things to exist together: an English landing page, a French landing page, and a row in BreadcrumbTranslations tying the two together with their labels. Miss any one of the three, and the breadcrumb either falls back to an untranslated raw folder name, or links somewhere less useful than intended.

That's a real, ongoing content operations question, not just a one-time setup task — and it's the subject of Part 2: how to make sure that dependency doesn't get missed as the site grows.