[Label] on a field: what a report calls it, in the reader's language

Where the platform names a field itself (a report's field picker, a column heading, a filter read back as a sentence), it says the field's `[Label("…")]`, or its name in words when it has none (`ArrivedAt` is "Arrived at"). Both are texts, exactly like an enum member's label: `osy translate` extracts them, and a reader sees them in their own language.

Summary#

A field's name is code; what a person reads for it is a word. Give the word with [Label]:

entity Parcel {
  [Label("Weight (kg)")] decimal Kilos;   // a report says "Weight (kg)"
  DateTime ArrivedAt;                     // a report says "Arrived at"
}

osy translate lists both in the locale files, and a Swedish reader's field picker says "Vikt (kg)" and "Inkom".

Signature#

[Label("<the words a person reads>")] <type> <Name>;   // on an entity field

Description#

When does a field's name need a label?#

When its name in words is not what your readers call it. ArrivedAt reads well as "Arrived at" and needs nothing; Kilos is better as "Weight (kg)", and Form as "Type". The label replaces the name wherever the platform names the field. Your own pages are untouched: a form's TextField("Weight", …) says what you wrote there.

Which field names are translated?#

Every declared [Label], and the name in words of every field a report's field picker can reach: the fields of each entity a report starts from (Explore.Root<Parcel>()), and of the entities three steps away through its references and collections, their bases' fields included, plus "Created at" and "Modified at", which every stored entity has. A field nothing reports on keeps its name to itself, so the locale files list only words somebody can read.

A field's words share one translation with every other label of the same words: a field called "Status" and an enum member labelled "Status" are one entry. Read on the server, in the language of the request (or the one Session.SetLanguage chose), so a field picker, its column headings and a filter's sentence all follow the reader.

Where a kit's fields are translated#

A kit's field is in the kit's locale file (sv.Osysharp.WorkQueues.osy), as its enum labels are, so an app that reports on a kit's entity translates the kit's field names once, beside the kit's other words.

Examples#

A field with a label, and one read by its name#

using Osysharp.Explore;

entity Courier { [Required, MaxLength(80)] string Name; }

entity Parcel {
  [Label("Weight (kg)")] decimal Kilos;
  DateTime ArrivedAt;
  Courier? Courier;
  security { allow read when IsAuthenticated; }
}

/// What the field picker offers for a parcel: "Weight (kg)", "Arrived at", "Courier", "Courier › Name" …
List<string> ParcelFieldWords() {
  return Explore.Fields(Explore.Root<Parcel>(), 2).Select(f => f.Label).ToList();
}