Building a site14 min read
Links and locales
Serving a site in several languages, and linking between pages by name so links follow them in every locale.
A collage site can serve every page in several languages, each at its own URL. It routes locales; it does not translate. What a word should be in Turkish lives in your content, wherever that already is — collage's part is knowing which URL belongs to which language, and building links that know it too. For the words in your templates, the elagoht/i18n plugin keeps a catalog per locale and translates in the locale the page is rendered in.
Configuring locales
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Locale: collage.LocaleConfig{
Default: "en",
Supported: []string{"en", "tr"},
},
})
Default is the locale of a URL with no locale prefix, and defaults to "en". Supported lists every locale the site serves, and must include Default (collage.ErrLocaleDefaultNotSupported otherwise); left empty, it is just Default.
A page then declares its path in each locale it exists in:
collage.NewPage("about").
WithLayouts(layout).
WithContent(about).
WithPath("en", "/about").
WithPath("tr", "/hakkinda").
Build()
The paths may differ, as here, or be the same pattern in every locale. A page with a path in only one locale exists only in that one.
The locale in WithPath is not a label. It picks which locale's routes the path joins, and a request only reaches a locale that is Default or in Supported. Default is "en" unless you set it, so a site in Turkish alone sets it:
Locale: collage.LocaleConfig{Default: "tr"},
and declares WithPath("tr", "/hakkinda").
A path in a locale no URL reaches is refused at registration with collage.ErrLocaleUnreachable, and the error names the page and the locale config, rather than the site starting and answering 404 at every URL. The same holds for actions and documents.
WithPath also refuses two more mistakes, for a page, a document or an action alike:
- a locale named twice:
collage.ErrDuplicateLocalePath, keeping the first path; - an empty locale:
collage.ErrInvalidLocale.
A path whose first segment is literal text naming Default or a supported locale, in any case, is refused with collage.ErrLocaleUnreachable too — for a page, a document, an action or a redirect source. That first segment is taken for the prefix and stripped, so /tr/guide.txt registered under en would be a request for /guide.txt in tr, which nothing answers. Write /guide.txt: the prefix is added for you.
A route that could never answer is refused at registration as well:
- a redirect whose source matches a page's or a document's path —
/{slug}next to a document at/about.txt— iscollage.ErrRedirectShadowsPage, since redirects win over routes: narrow the redirect's source; - a redirect whose destination its own source matches,
/docsto/docs/say, iscollage.ErrRedirectLoop; - a pattern that uses one placeholder name twice is
collage.ErrInvalidPattern.
The URL decides the locale
A path with no locale prefix is in Default. A path whose first segment names a supported locale is in that locale, and the prefix is removed before the path is matched:
| URL | Locale | Matched against |
|---|---|---|
/about | en | /about in the en paths |
/tr/hakkinda | tr | /hakkinda in the tr paths |
/tr/about | tr | /about in the tr paths — not found, a 404 |
/fr/about | en | /fr/about — fr is not supported, so it is an ordinary segment |
/en/about | — | Redirected to /about |
/TR/hakkinda | — | Redirected to /tr/hakkinda |
Default: "en" and Supported: []string{"en", "tr"}, and no PrefixDefault, the first segment of the path picks the locale. No supported locale there means the default, with the path as it came. tr means Turkish, with the prefix removed. The default's own prefix, or a locale in another case, is redirected to the one spelling before any page is looked up. What is left is matched among that locale's paths only.Each page has one URL per locale, so the other spellings of a prefix redirect permanently to it:
- the default locale's own prefix, which its URLs do not carry;
- a supported locale in another case.
The redirect is a 301 for a GET or a HEAD and a 308 for anything else, so a form posted to the wrong spelling is posted again rather than turned into a GET, and the query string goes along. Without it, /en/about would be a second copy of /about for a search engine and a second entry in the cache.
A site that wants every language under a prefix, the default one included, sets PrefixDefault: true. Then /en/about is the page beside /tr/hakkinda, and a bare URL is no language at all:
- A page requested without a prefix —
/about, or the root — redirects permanently to the default locale's address,/en/aboutand/en. - Every link built by name carries the prefix.
- Documents are prefixed the same way,
/en/sitemap.xmlbeside/tr/sitemap.xml, except the site's own files, built withAtRoot:/robots.txtis at the root and nowhere else. - An export writes the default locale under
en/, and at its root a copy of the/en/home that names/en/as its canonical address.
PrefixDefault: true every language has a prefix. A default-locale page asked for at its bare address is redirected to the prefixed one with a 301, the root included. A static host has nothing to send the bare domain on to the prefixed home, so the export writes the default locale's pages under en/ and puts a copy of the /en/ home at its root, naming /en/ as its canonical address.A fragment reads the result as rc.Locale, and uses it to fetch the right content:
func aboutData(ctx context.Context, rc *collage.RenderContext) (aboutView, []string, error) {
text, err := cms.Page(ctx, "about", rc.Locale)
if err != nil {
return aboutView{}, nil, err
}
return aboutView{Body: text}, []string{"page:about:" + rc.Locale}, nil
}
There is no switch that turns prefixes off. A site in one language registers its paths in Default, which carries no prefix, and one that negotiates on its own does it in middleware.
Why only the URL
collage never picks a locale from the Accept-Language header or a cookie.
A URL whose content depends on who is asking is one URL with several contents, and everything that stores URLs gets it wrong: a cache serves the first reader's language to everyone, a search engine indexes one version and never sees the other, and a link someone shares opens in a language they did not send. It also breaks in a less obvious way — a Turkish browser following a link to /about would be looked up among the Turkish paths, where /about does not exist, and be handed a 404.
With the locale in the URL, each URL means one thing, for every reader and every cache. If you do want to use the reader's preferences, you still can, deliberately — see below.
Links by name
A link written as a path breaks silently when the path changes, and cannot know which locale it is in. Link by the name the page was registered under:
<a href="{{pageURL "about"}}">About</a>
<a href="{{pageURL "blog-post" "slug" .Slug}}">{{.Title}}</a>
<link rel="alternate" type="application/rss+xml" href="{{pageURL "feed"}}">
pageURL takes the page's name and then its path parameters as name–value pairs. It works for documents as well as pages.
- It follows the render's locale. On
/tr/hakkinda,{{pageURL "about"}}is/tr/hakkinda; on/aboutit is/about. The prefix is added for you. - It falls back to the default locale. A page with no path in the current locale links its default-locale path, so a Turkish page linking a page that exists only in English still renders.
- It is strict. An unknown name, a missing or empty parameter, or a parameter the pattern has no placeholder for fails the render. A link that cannot be built is a bug to find in development, not a 404 for a reader.
- Values are escaped, and a value of
.or..is refused. - Values are strings, integers or
fmt.Stringers:{{pageURL "user" "id" .ID}}. - It ends in
/whenTrailingSlashis on — a page's link, not a document's:/about/,/tr/, but/feed.xml. A document's or an action's link never ends in/: that is its one spelling, and the other is redirected to it, with a301for a document and a308for an action.
{{pageURL "about"}} in a shared layout is /about on the English page and /tr/hakkinda on the Turkish one. A page with no path in the render's locale, here a careers page that exists only in English, is linked at its default-locale path.A link in a specific locale
pageURLIn takes the locale first, and links exactly that locale — no fallback:
<a href="{{pageURLIn "tr" "about"}}" hreflang="tr">Hakkımızda</a>
A page with no path in that locale fails the render, as does a locale the site does not support.
A language switcher
localeURL is the page being rendered, in another locale, with the same path parameters. It is empty when the page has no path in that locale, so with skips a language the page has not been translated into:
<nav class="languages">
{{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
{{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}
</nav>
Put it in the layout and every page gets a switcher that only offers what exists. A locale that is not supported at all is still an error — that is a typo in the template, not an untranslated page.
Path parameters are carried over as they are. A page at /blog/{slug} in both locales switches from /blog/hello to /tr/blog/hello; if your Turkish posts have Turkish slugs, the switcher cannot know that, and you build that link yourself from your content.
Telling search engines about translations
A switcher is for readers. Search engines learn a page's translations from <link rel="alternate" hreflang="…"> in its head, which rc.HoistAlternate(hreflang, href) declares, one per language. Pair it with app.URL for each locale the page exists in — Head and SEO has a layout that does it for every page.
A form posting to an action at its own URL names the action the same way, with {{actionURL "logout"}}.
Links from Go
In a data handler or an action — a redirect to a named page, a canonical URL — use rc.URL, and rc.ActionURL for an action. They build in the render's own locale and fall back to the default one, as pageURL and actionURL do, so nothing has to hand the *App to the code that needs a link:
target, err := rc.URL("blog-post", map[string]string{"slug": post.Slug})
if err != nil {
return nil, err
}
return collage.SeeOther(target), nil
func (rc *RenderContext) URL(name string, params map[string]string) (string, error)
func (rc *RenderContext) ActionURL(name string, params map[string]string) (string, error)
A value, even one straight from the request, is one escaped path segment: one holding /, or being . or .., is collage.ErrRouteParams, so it cannot turn the path into another site's URL. On a RenderContext collage did not make — one a test builds by hand — both return collage.ErrUnknownRoute.
In a guard or a middleware, which run in a request but have no render, it is collage.URL(ctx, name, params): the same builder, in the locale the request resolved to — the default one in a middleware, which runs before routing — and ErrUnknownRoute outside a request collage serves. collage.GuardSeeOtherPage(ctx, name, params) turns it into a guard's redirect (see Pages and layouts).
For a locale other than the render's own, or outside a render — a sitemap listing every page, the alternates in a page's head — use app.URL, which takes the locale:
target, err := app.URL("blog-post", "tr", map[string]string{"slug": post.Slug})
func (a *App) URL(name, locale string, params map[string]string) (string, error)
An empty locale means the default one. It is as strict as pageURLIn:
| What is wrong | Error |
|---|---|
| An unknown name | collage.ErrUnknownRoute |
| A locale the route has no path in | collage.ErrNoPathInLocale |
| Parameters that do not fill the pattern exactly | collage.ErrRouteParams |
| A locale no URL can carry — neither the default nor supported | collage.ErrLocaleUnreachable |
The result is a path, prefix included; add your site's origin when you need an absolute URL.
A fragment's URL
A fragment a page opened at its own URL with WithFragmentPath is linked the same way, by the page's name and the fragment's:
<div data-live="{{fragmentURL "home" "cpu-usage"}}">{{slot "cpu-usage"}}</div>
<div data-live="{{fragmentURL "post" "comments" "slug" .Slug}}">…</div>
fragmentURL uses the render's locale and falls back to the default one; fragmentURLIn "tr" "home" "cpu-usage" names the locale. In Go it is app.FragmentURL:
func (a *App) FragmentURL(page, fragment, locale string, params map[string]string) (string, error)
It is as strict as app.URL:
| What is wrong | Error |
|---|---|
| An unknown page | collage.ErrUnknownRoute |
| A fragment the page did not open | collage.ErrUnknownFragmentPath |
| A fragment opened at two paths in one locale | collage.ErrAmbiguousFragmentPath |
| Missing parameters | collage.ErrRouteParams |
In a template, each fails the render.
Negotiating a language yourself
Choosing a language from the reader's browser is a decision about your site, so it is yours to make, in middleware. There are two honest ways to do it.
Redirect a reader who arrives at the default-locale home page with a Turkish browser, or a language cookie of your own, to /tr. Every URL still means one thing; you have only chosen where a new reader starts.
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/" && strings.HasPrefix(r.Header.Get("Accept-Language"), "tr") {
http.Redirect(w, r, "/tr", http.StatusFound)
return
}
next.ServeHTTP(w, r)
})
})
Render one URL in the reader's language. Decide in middleware, pass the decision to data handlers through the request context, and tell collage with collage.Vary, so the cache keeps one copy per language:
type langKey struct{}
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
lang := "en"
if strings.HasPrefix(r.Header.Get("Accept-Language"), "tr") {
lang = "tr"
}
collage.Vary(r, "Accept-Language", lang)
next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), langKey{}, lang)))
})
})
func pageData(ctx context.Context, rc *collage.RenderContext) (pageView, []string, error) {
lang, _ := ctx.Value(langKey{}).(string)
// ...
}
Vary puts the value you resolved — "tr", not the browser's whole header — into the page's cache key, and the header name into the response's Vary header, so a CDN keeps the versions apart too.
It must be called from middleware. Vary closes when routing begins, on every route — cached or not — so a call from a data handler, or anywhere else after routing, changes nothing and returns collage.ErrVaryTooLate.
This is the shape that trades the benefits of one URL, one content away, so choose it knowingly — usually on a site whose pages all have their paths in Default, so no URL names a locale.
A static export renders without requests, so no middleware runs for the files it writes: an exported site can only have its locales in its URLs.
Example: a bilingual product catalogue
A shop sells in English and Turkish. Its two pages have a path in each locale, and the product page opens its stock box at a URL of its own, so a script can refresh it:
| Page | en | tr |
|---|---|---|
catalogue | /products | /tr/urunler |
product | /products/{id} | /tr/urunler/{id} |
product's stock box | /products/{id}/stock | /tr/urunler/{id}/stok |
The locale configuration is the one above: Default: "en", Supported: []string{"en", "tr"}. The catalog package stands for your own data layer; it keeps each product's name in both languages, and the handlers ask it for the render's locale:
func loadCatalogue(ctx context.Context, rc *collage.RenderContext) ([]catalog.Product, []string, error) {
list, err := catalog.List(ctx, rc.Locale)
if err != nil {
return nil, nil, err
}
return list, []string{"catalog"}, nil
}
func loadProduct(ctx context.Context, rc *collage.RenderContext) (catalog.Product, []string, error) {
id := rc.Param("id")
p, err := catalog.Find(ctx, id, rc.Locale)
if errors.Is(err, catalog.ErrNoProduct) {
return catalog.Product{}, nil, fmt.Errorf("catalog: no product %q: %w", id, collage.ErrNotFound)
}
if err != nil {
return catalog.Product{}, nil, err
}
return p, []string{"product:" + id}, nil
}
func loadStock(ctx context.Context, rc *collage.RenderContext) (int, error) {
return catalog.Stock(ctx, rc.Param("id"))
}
Each page declares a path per locale, and the product page opens the stock fragment in each:
layout := collage.NewFragment("layout", "layouts/master.html").Build()
stock := collage.NewFragment("product-stock", "fragments/stock.html").
WithData(collage.Load(loadStock)).
Build()
catalogue := collage.NewPage("catalogue").
WithLayouts(layout).
WithContent(collage.NewFragment("catalogue", "pages/catalogue.html").
WithData(collage.LoadTagged(loadCatalogue)).
Build()).
WithPath("en", "/products").
WithPath("tr", "/urunler").
Build()
product := collage.NewPage("product").
WithLayouts(layout).
WithContent(collage.NewFragment("product", "pages/product.html").
WithData(collage.LoadTagged(loadProduct)).
WithSlotFragment("stock", stock).
Build()).
WithPath("en", "/products/{id}").
WithPath("tr", "/urunler/{id}").
WithFragmentPath("en", "/products/{id}/stock", stock).
WithFragmentPath("tr", "/urunler/{id}/stok", stock).
Build()
if err := app.Register(catalogue, product); err != nil {
return err
}
The templates name pages, never paths. The layout carries the language switcher, the catalogue links each product by name with its id, and the product page names its stock box's URL:
<!-- templates/layouts/master.html -->
<nav class="languages">
{{with localeURL "en"}}<a hreflang="en" href="{{.}}">English</a>{{end}}
{{with localeURL "tr"}}<a hreflang="tr" href="{{.}}">Türkçe</a>{{end}}
</nav>
{{slot "content"}}
<!-- templates/pages/catalogue.html -->
<ul>
{{range .}}
<li><a href="{{pageURL "product" "id" .ID}}">{{.Name}}</a></li>
{{end}}
</ul>
<!-- templates/pages/product.html -->
<article>
<h1>{{.Name}}</h1>
<div data-live="{{fragmentURL "product" "product-stock" "id" .ID}}">{{slot "stock"}}</div>
</article>
<!-- templates/fragments/stock.html -->
<p class="stock">{{.}}</p>
On /tr/urunler/42, the links come out as:
| In the template | Becomes |
|---|---|
localeURL "en" | /products/42 |
localeURL "tr" | /tr/urunler/42 |
pageURL "product" "id" .ID, in the catalogue | /tr/urunler/42 |
fragmentURL "product" "product-stock" "id" .ID | /tr/urunler/42/stok |
On /products/42 the same templates give /products/42 and /products/42/stock. A few things make this work:
- Both patterns name the parameter
{id}.localeURLcarries the render's parameters over by name, and a pattern they do not fill fails the render. The id is the same number in both languages, so the switcher needs nothing else; a slug translated per language would need the link built from your content, as above. fragmentURLnames the fragment, not the slot:product-stock, the name given toNewFragment.- The stock box has a path in each locale. With only the English one, a Turkish page would link
/products/42/stock, its default-locale fallback. - The wrong spellings are handled for you.
/en/products/42redirects to/products/42, and/tr/products/42is a 404, since/products/{id}is not among the Turkish paths.