Put locale in compliance portal URLs

Path-segment locales make each language crawlable with self
canonical and hreflang, while identity.locale persists an
explicit choice without client storage or cookie banners.

Signed-off-by: Émile Ré <emile@probo.com>

pkg/server/api/complianceportal/v1/auth_resolvers.go

@@ -97,6 +97,42 @@ func (r *mutationResolver) UpdateFullName(ctx context.Context, input types.Updat
 	return &types.UpdateFullNamePayload{Success: true}, nil
 }
 
+// UpdateLocale is the resolver for the updateLocale field.
+func (r *mutationResolver) UpdateLocale(ctx context.Context, input types.UpdateLocaleInput) (*types.UpdateLocalePayload, error) {
+	identity := authn.IdentityFromContext(ctx)
+	if identity == nil {
+		return nil, gqlutils.Unauthenticatedf(ctx, "authentication is required to update locale")
+	}
+
+	identity, err := r.iam.AccountService.UpdateLocale(
+		ctx,
+		identity.ID,
+		&iam.UpdateLocaleRequest{
+			Locale: input.Locale,
+		},
+	)
+	if err != nil {
+		if validationErrors, ok := errors.AsType[validator.ValidationErrors](err); ok {
+			return nil, gqlutils.InvalidValidationErrors(ctx, validationErrors)
+		}
+
+		r.logger.ErrorCtx(ctx, "cannot update identity locale", log.Error(err))
+		return nil, gqlutils.Internal(ctx)
+	}
+
+	return &types.UpdateLocalePayload{
+		Identity: &types.Identity{
+			ID:            identity.ID,
+			Email:         identity.EmailAddress,
+			FullName:      identity.FullName,
+			EmailVerified: identity.EmailAddressVerified,
+			Locale:        identity.Locale,
+			CreatedAt:     identity.CreatedAt,
+			UpdatedAt:     identity.UpdatedAt,
+		},
+	}, nil
+}
+
 // SignOut is the resolver for the signOut field.
 func (r *mutationResolver) SignOut(ctx context.Context) (*types.SignOutPayload, error) {
 	session := authn.SessionFromContext(ctx)

pkg/server/api/complianceportal/v1/base_resolvers.go

@@ -35,6 +35,7 @@ func (r *queryResolver) Viewer(ctx context.Context) (*types.Identity, error) {
 		Email:         identity.EmailAddress,
 		FullName:      identity.FullName,
 		EmailVerified: identity.EmailAddressVerified,
+		Locale:        identity.Locale,
 		CreatedAt:     identity.CreatedAt,
 		UpdatedAt:     identity.UpdatedAt,
 	}, nil

pkg/server/api/complianceportal/v1/graphql/auth.graphql

@@ -1,6 +1,8 @@
 extend type Mutation {
   updateFullName(input: UpdateFullNameInput!): UpdateFullNamePayload
     @authentication(required: PRESENT) @sessionOnly
+  updateLocale(input: UpdateLocaleInput!): UpdateLocalePayload
+    @authentication(required: PRESENT) @sessionOnly
   signOut: SignOutPayload! @authentication(required: PRESENT) @sessionOnly
 }
 
@@ -12,6 +14,15 @@ type UpdateFullNamePayload {
   success: Boolean!
 }
 
+input UpdateLocaleInput {
+  # Short URL locale tag (en, fr, de, …).
+  locale: String!
+}
+
+type UpdateLocalePayload {
+  identity: Identity!
+}
+
 type SignOutPayload {
   success: Boolean!
 }

pkg/server/api/complianceportal/v1/graphql/base.graphql

@@ -54,6 +54,9 @@ type Identity implements Node {
   email: EmailAddr!
   fullName: String!
   emailVerified: Boolean!
+  # Preferred UI locale as a short URL tag (en, fr, de, …). Null until the
+  # viewer explicitly chooses a language in the portal.
+  locale: String
   createdAt: Datetime!
   updatedAt: Datetime!
 }

pkg/server/api/complianceportal/v1/mux.go

@@ -134,16 +134,21 @@ func compliancePageHeadData() HeadDataFunc {
 		}
 
 		compliancePageBaseURL := complianceportal.CompliancePortalBaseURLFromContext(r.Context())
+		pageBase := ref.UnrefOrZero(compliancePageBaseURL)
+		htmlLang, canonical, hreflang := SEOFromRequest(r, pageBase)
 
-		description := tc.Title + " Compliance Page"
+		description := tc.Title
 		if tc.Description != nil && *tc.Description != "" {
 			description = *tc.Description
 		}
 
 		headData := HeadData{
-			Title:       tc.Title,
-			Description: description,
-			OGURL:       ref.UnrefOrZero(compliancePageBaseURL),
+			Title:        tc.Title,
+			Description:  description,
+			OGURL:        pageBase,
+			HtmlLang:     htmlLang,
+			CanonicalURL: canonical,
+			Hreflang:     hreflang,
 		}
 
 		if tc.LogoFileID != nil && compliancePageBaseURL != nil {

pkg/server/api/complianceportal/v1/seo.go

@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+package complianceportal_v1
+
+import (
+	"net/http"
+	"strings"
+)
+
+// Short locale tags used in compliance-portal URL paths. Keep in sync with the
+// frontend URL_LOCALES list and iam.supportedIdentityLocales.
+var compliancePortalLocales = []string{
+	"en", "fr", "de", "es", "id", "it", "ja", "ko", "pl", "pt", "tr", "uk", "zh",
+}
+
+const defaultCompliancePortalLocale = "en"
+
+// SEOFromRequest derives html lang, a self-referencing canonical URL, and
+// hreflang alternates (including x-default → English) for the SPA shell.
+func SEOFromRequest(r *http.Request, pageBaseURL string) (htmlLang, canonical string, hreflang []HreflangLink) {
+	appPath := complianceAppPath(r.URL.Path)
+	locale, rest := splitLocaleFromAppPath(appPath)
+
+	htmlLang = locale
+	canonical = localizedPageURL(pageBaseURL, locale, rest)
+
+	hreflang = make([]HreflangLink, 0, len(compliancePortalLocales)+1)
+	for _, loc := range compliancePortalLocales {
+		hreflang = append(hreflang, HreflangLink{
+			Lang: loc,
+			Href: localizedPageURL(pageBaseURL, loc, rest),
+		})
+	}
+	hreflang = append(hreflang, HreflangLink{
+		Lang: "x-default",
+		Href: localizedPageURL(pageBaseURL, defaultCompliancePortalLocale, rest),
+	})
+
+	return htmlLang, canonical, hreflang
+}
+
+// complianceAppPath returns the path relative to the portal root: under
+// /trust/:slug it strips that prefix; on a custom domain it returns the path as-is.
+func complianceAppPath(pathname string) string {
+	trimmed := strings.TrimPrefix(pathname, "/")
+	if strings.HasPrefix(trimmed, "trust/") {
+		parts := strings.SplitN(trimmed, "/", 3)
+		if len(parts) < 2 {
+			return "/"
+		}
+		if len(parts) == 2 {
+			return "/"
+		}
+		return "/" + parts[2]
+	}
+	if pathname == "" {
+		return "/"
+	}
+	return pathname
+}
+
+func splitLocaleFromAppPath(appPath string) (locale, rest string) {
+	segments := strings.Split(strings.Trim(appPath, "/"), "/")
+	if len(segments) == 0 || segments[0] == "" {
+		return defaultCompliancePortalLocale, "/"
+	}
+
+	if isCompliancePortalLocale(segments[0]) {
+		locale = segments[0]
+		if len(segments) == 1 {
+			return locale, "/"
+		}
+		return locale, "/" + strings.Join(segments[1:], "/")
+	}
+
+	// Unprefixed legacy path — treat content path as-is; default lang for tags.
+	return defaultCompliancePortalLocale, appPath
+}
+
+func isCompliancePortalLocale(value string) bool {
+	for _, locale := range compliancePortalLocales {
+		if locale == value {
+			return true
+		}
+	}
+	return false
+}
+
+func localizedPageURL(pageBaseURL, locale, rest string) string {
+	base := strings.TrimRight(pageBaseURL, "/")
+	if rest == "/" || rest == "" {
+		return base + "/" + locale
+	}
+	if !strings.HasPrefix(rest, "/") {
+		rest = "/" + rest
+	}
+	return base + "/" + locale + rest
+}

pkg/server/api/complianceportal/v1/seo_test.go

@@ -0,0 +1,55 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+package complianceportal_v1_test
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	complianceportal_v1 "go.probo.inc/probo/pkg/server/api/complianceportal/v1"
+)
+
+func TestSEOFromRequest(t *testing.T) {
+	t.Parallel()
+
+	req, err := http.NewRequest(http.MethodGet, "https://app.example.com/trust/acme/fr/documents", nil)
+	require.NoError(t, err)
+
+	lang, canonical, hreflang := complianceportal_v1.SEOFromRequest(req, "https://app.example.com/trust/acme")
+	assert.Equal(t, "fr", lang)
+	assert.Equal(t, "https://app.example.com/trust/acme/fr/documents", canonical)
+	require.NotEmpty(t, hreflang)
+
+	var xDefault string
+	var enHref string
+	for _, link := range hreflang {
+		if link.Lang == "x-default" {
+			xDefault = link.Href
+		}
+		if link.Lang == "en" {
+			enHref = link.Href
+		}
+	}
+	assert.Equal(t, "https://app.example.com/trust/acme/en/documents", enHref)
+	assert.Equal(t, enHref, xDefault)
+}

pkg/server/api/complianceportal/v1/spa.go

@@ -33,10 +33,18 @@ import (
 
 type (
 	HeadData struct {
-		Title       string
-		Description string
-		OGURL       string
-		FaviconURL  string
+		Title        string
+		Description  string
+		OGURL        string
+		FaviconURL   string
+		HtmlLang     string
+		CanonicalURL string
+		Hreflang     []HreflangLink
+	}
+
+	HreflangLink struct {
+		Lang string
+		Href string
 	}
 
 	HeadDataFunc func(r *http.Request) HeadData