Localized fields
On an entry or a global, a field is shared across languages unless it chains .localized(). This page covers the rule, where it applies and what it means for queries.
The rule
.localized() gives a field its own value per language. Without it, one value serves every language:
export const people = smoodly.collection({
name: "people",
title: "People",
titleField: "name",
order: "manual",
fields: {
name: f.text(),
role: f.text().localized(),
},
});A person's name is the same in Finnish and English; the role is translated. Shared is the default because most of an entry is: the photo, the date, the author, the price. The starter's articles localize the title, the excerpt, the body and the tags, and share the image, the date and the author.
A global follows the same rule. The contact details share the email and localize the address; the header shares the brand and localizes the navigation.
Where it applies
Collection and global fieldsDecides storage: the field gets a value per language.slugAlways per language, with or without .localized(): each language has its own URL.Lists and objectsLocalizes the whole value. Inside an item or a subfield it is a type error; localize the top-level field that holds it, for a list of objects the list.SettingsNever. A layout choice is the same in every language, and .localized() on a setting throws.Page fieldsNot needed: page fields are stored per language already.Section fields on a pageNo effect on storage. A page's content is per language as a whole.A page's whole tree is per language: adding a language copies the tree, and from then on the two are edited apart. That is why a page's sections need no .localized(), and why a change made in English is not mirrored in Finnish.
In the form
On a multilingual site the entry and Globals forms mark every shared field with a globe-off icon, so an editor translating knows which values will change in every language at once. Adding a language copies every field as the first draft, shared and localized alike; the shared ones then stay in step by themselves.
Changing it later
Adding or removing .localized() on a field that already holds content moves nothing in storage:
- Turning it on: the value saved while the field was shared stays as every language's fallback. Each language shows it until an editor saves that language, which gives the language its own value. Until then, the form's notice says the value is still shared.
- Turning it off: each language keeps showing its own value until it is saved. The first save in a language makes that language's value the one every language shows, and the form warns about it before the save.
When the schema changes covers the other changes and the Content health page that lists them.
In code
Reads merge the shared and the localized values for the language asked, so a view sees one flat set of fields. Two things follow from the split:
- A
wherefilter in a query matches shared fields only. Filtering on a localized field or on the slug is refused, because those live per language. - A collection's
order.bymust be a shared field, because the order is one list for every language.