Skip to content
v0.3.3

Expression files

Store built-in component labels and messages in JSON or YAML, then load them as an expressions.Set. Your application chooses which set to use; Goshtoso supplies English text for fields you leave unspecified.

Load and render

Create locales/pt.yaml with the text you want to replace. Group and property names match the Go API exactly, including capitalization. This file replaces the empty-state title and description, along with three pagination labels.

locales/pt.yaml 
# yaml-language-server: $schema=./expressions.schema.json
EmptyState:
  Title: Ainda não há nada aqui
  Description: Os itens aparecerão aqui quando estiverem disponíveis.
Pagination:
  NextLabel: Próxima
  NextAriaLabel: Próxima página
  PageAriaLabel: Página {page}

Save the following program as main.go beside the locales directory. It embeds the YAML file in the executable, loads the expressions, and writes an empty-state component’s HTML to standard output. The rendered title and description come from the file.

main.go 
package main

import (
    "context"
    "embed"
    "log"
    "os"

    "github.com/araihu/goshtoso/components/emptystate"
    "github.com/araihu/goshtoso/expressions"
)

//go:embed locales/pt.yaml
var locales embed.FS

func main() {
    set, err := expressions.LoadFS(locales, "locales/pt.yaml")
    if err != nil {
        log.Fatal(err)
    }

    renderer := expressions.NewRenderer(set)
    component := emptystate.EmptyState(emptystate.Config{})
    if err := renderer.Render(context.Background(), os.Stdout, component); err != nil {
        log.Fatal(err)
    }
}

In a web application, create the renderer at startup and reuse it in your handlers, passing the request context and response writer to Render. To support several languages, load each file once and choose a set for each request.

See the Internationalization guide to configure application defaults and request overrides, or try the live examples.

Files and byte slices

LoadFS accepts any fs.FS, including embed.FS and os.DirFS. Use LoadFile when you have a disk path, or ParseJSON and ParseYAML when the contents are already available as []byte. The file loaders select the format from the .json, .yaml, or .yml extension. All four functions return (Set, error); check the error before using the set.

JSON uses the same groups and properties as YAML. For example, these are the pagination overrides from the YAML file above:

locales/pt.json 
{
  "$schema": "./expressions.schema.json",
  "Pagination": {
    "NextLabel": "Próxima",
    "NextAriaLabel": "Próxima página",
    "PageAriaLabel": "Página {page}"
  }
}

Omitted fields and empty strings leave existing defaults in place. A loaded set contains only the supplied overrides, so it can also be passed to expressions.With or combined with another set using expressions.Merge.

Messages with values

Some messages include a value supplied by the component. Pagination.PageAriaLabel uses {page}: “Página {page}” produces “Página 3” for page 3. Each message accepts only the placeholder listed in the reference below. Use {{ and }} to include literal braces.

File messages substitute values as text. For plural forms or locale-specific number formatting, assign a Go callback to the field after loading the set.

Validation and property reference

The loaders reject unknown or duplicate properties, nulls, non-string expressions, invalid placeholders, and multiple documents. In YAML, quote numbers and booleans when you intend them as text. YAML aliases and merge keys are not supported.

Download the JSON Schema to use it in your editor.

Save the schema as expressions.schema.json beside your translation files. The YAML comment and JSON $schema property shown above associate the file with the schema in editors that support it, enabling property completion and validation while you edit. You can also obtain the schema with expressions.JSONSchema(). The loaders validate the input themselves and do not fetch the $schema URL.

Expand a component below to see its supported properties, English defaults, and message placeholders.

  • $schema string optional

    Optional editor schema reference. Goshtoso does not fetch this URL.

  • ActionGroup object optional

    ActionGroup expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "Actions".

      English
      Actions
    • OverflowAriaLabel string optional

      OverflowAriaLabel defaults to "More actions".

      English
      More actions
  • Alert object optional

    Alert expressions. Omitted or empty fields inherit defaults.

    • DismissAriaLabel string optional

      DismissAriaLabel defaults to "dismiss alert".

      English
      dismiss alert
    • DismissLabel string optional

      DismissLabel defaults to "Dismiss".

      English
      Dismiss
  • AppShell object optional

    AppShell expressions. Omitted or empty fields inherit defaults.

    • SkipLinkLabel string optional

      SkipLinkLabel defaults to "Skip to main content".

      English
      Skip to main content
  • Avatar object optional

    Avatar expressions. Omitted or empty fields inherit defaults.

    • GroupAriaLabel string optional

      GroupAriaLabel defaults to "Avatar group".

      English
      Avatar group
  • Badge object optional

    Badge expressions. Omitted or empty fields inherit defaults.

    • NotificationAriaLabel string optional

      NotificationAriaLabel defaults to "notification".

      English
      notification
  • Banner object optional

    Banner expressions. Omitted or empty fields inherit defaults.

    • AcceptLabel string optional

      AcceptLabel defaults to "Accept".

      English
      Accept
    • ConsentAriaLabel string optional

      ConsentAriaLabel defaults to "Cookie consent".

      English
      Cookie consent
    • DismissAriaLabel string optional

      DismissAriaLabel defaults to "dismiss banner".

      English
      dismiss banner
    • RejectLabel string optional

      RejectLabel defaults to "Decline".

      English
      Decline
    • Title string optional

      Title defaults to "Cookie Consent".

      English
      Cookie Consent
  • Breadcrumbs object optional

    Breadcrumbs expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "breadcrumb".

      English
      breadcrumb
  • Carousel object optional

    Carousel expressions. Omitted or empty fields inherit defaults.

    • LoadingText string optional

      LoadingText defaults to "Loading carousel...".

      English
      Loading carousel...
    • NextAriaLabel string optional

      NextAriaLabel defaults to "next slide".

      English
      next slide
    • PauseAriaLabel string optional

      PauseAriaLabel defaults to "pause carousel".

      English
      pause carousel
    • PlayAriaLabel string optional

      PlayAriaLabel defaults to "play carousel".

      English
      play carousel
    • PreviousAriaLabel string optional

      PreviousAriaLabel defaults to "previous slide".

      English
      previous slide
    • SlideLabel string optional

      SlideLabel returns the carousel counter text for slide. Rendering prepares values from zero through the number of slides; visible slide numbers start at one. In files, use {slide} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      slide {slide}
      Placeholder
      {slide}
    • SlidesAriaLabel string optional

      SlidesAriaLabel defaults to "slides".

      English
      slides
  • ChatBubble object optional

    ChatBubble expressions. Omitted or empty fields inherit defaults.

    • BotLabel string optional

      BotLabel defaults to "BOT".

      English
      BOT
    • DeliveredLabel string optional

      DeliveredLabel defaults to "Delivered".

      English
      Delivered
    • SeenLabel string optional

      SeenLabel defaults to "Seen".

      English
      Seen
    • SendingLabel string optional

      SendingLabel defaults to "Sending".

      English
      Sending
    • TypingAriaLabel string optional

      TypingAriaLabel defaults to "typing".

      English
      typing
  • CodeBlock object optional

    CodeBlock expressions. Omitted or empty fields inherit defaults.

    • CopiedLabel string optional

      CopiedLabel defaults to "Copied!".

      English
      Copied!
    • CopyAriaLabel string optional

      CopyAriaLabel returns the copy button’s accessible name for the code block header label, or its ID when no label is available. In files, use {label} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      Copy {label} code
      Placeholder
      {label}
    • CopyLabel string optional

      CopyLabel defaults to "Copy".

      English
      Copy
    • ErrorText string optional

      ErrorText defaults to "Unable to copy".

      English
      Unable to copy
  • Combobox object optional

    Combobox expressions. Omitted or empty fields inherit defaults.

    • ClearLabel string optional

      ClearLabel defaults to "Clear all".

      English
      Clear all
    • EmptyText string optional

      EmptyText defaults to "No matches found".

      English
      No matches found
    • ErrorText string optional

      ErrorText defaults to "Failed to load.".

      English
      Failed to load.
    • Placeholder string optional

      Placeholder defaults to "Select…".

      English
      Select…
    • RetryLabel string optional

      RetryLabel defaults to "Retry".

      English
      Retry
    • SearchPlaceholder string optional

      SearchPlaceholder defaults to "Search…".

      English
      Search…
    • SelectedLabel string optional

      SelectedLabel returns the complete selection summary for count selected values. It must handle zero and positive counts; client components prepare all possible counts during rendering. In files, use {count} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      {count} selected
      Placeholder
      {count}
  • Drawer object optional

    Drawer expressions. Omitted or empty fields inherit defaults.

    • CloseAriaLabel string optional

      CloseAriaLabel defaults to "Close".

      English
      Close
  • Dropdown object optional

    Dropdown expressions. Omitted or empty fields inherit defaults.

    • ContextMenuAriaLabel string optional

      ContextMenuAriaLabel defaults to "context menu".

      English
      context menu
    • OpenMenuAriaLabel string optional

      OpenMenuAriaLabel defaults to "open menu".

      English
      open menu
  • EmptyState object optional

    EmptyState expressions. Omitted or empty fields inherit defaults.

    • Description string optional

      Description defaults to "Items will appear here when they are available.".

      English
      Items will appear here when they are available.
    • Title string optional

      Title defaults to "Nothing here yet".

      English
      Nothing here yet
  • FileInput object optional

    FileInput expressions. Omitted or empty fields inherit defaults.

    • BrowseLabel string optional

      BrowseLabel defaults to "Browse".

      English
      Browse
    • DropText string optional

      DropText defaults to " or drag and drop here".

      English
      or drag and drop here
    • EmptyText string optional

      EmptyText defaults to "No file selected".

      English
      No file selected
  • Form object optional

    Form expressions. Omitted or empty fields inherit defaults.

    • DoneLabel string optional

      DoneLabel defaults to "Done".

      English
      Done
    • EditLabel string optional

      EditLabel defaults to "Edit".

      English
      Edit
    • ErrorTitle string optional

      ErrorTitle defaults to "Validation failed".

      English
      Validation failed
  • Modal object optional

    Modal expressions. Omitted or empty fields inherit defaults.

    • CloseAriaLabel string optional

      CloseAriaLabel defaults to "close modal".

      English
      close modal
    • DialogCloseAriaLabel string optional

      DialogCloseAriaLabel defaults to "Close dialog".

      English
      Close dialog
  • Navbar object optional

    Navbar expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "main navigation".

      English
      main navigation
    • CloseMenuAriaLabel string optional

      CloseMenuAriaLabel defaults to "Close mobile menu".

      English
      Close mobile menu
    • OpenMenuAriaLabel string optional

      OpenMenuAriaLabel defaults to "Open mobile menu".

      English
      Open mobile menu
    • SecondaryAriaLabel string optional

      SecondaryAriaLabel defaults to "secondary navigation".

      English
      secondary navigation
    • UserMenuAriaLabel string optional

      UserMenuAriaLabel defaults to "user menu".

      English
      user menu
  • Pagination object optional

    Pagination expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "pagination".

      English
      pagination
    • MoreAriaLabel string optional

      MoreAriaLabel defaults to "more pages".

      English
      more pages
    • NextAriaLabel string optional

      NextAriaLabel defaults to "next page".

      English
      next page
    • NextLabel string optional

      NextLabel defaults to "Next".

      English
      Next
    • PageAriaLabel string optional

      PageAriaLabel returns the accessible name for a page link. Page numbers start at one. In files, use {page} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      page {page}
      Placeholder
      {page}
    • PreviousAriaLabel string optional

      PreviousAriaLabel defaults to "previous page".

      English
      previous page
    • PreviousLabel string optional

      PreviousLabel defaults to "Previous".

      English
      Previous
  • Palette object optional

    Palette expressions. Omitted or empty fields inherit defaults.

    • BlackLabel string optional

      BlackLabel defaults to "black".

      English
      black
    • CustomLabel string optional

      CustomLabel defaults to "Custom color".

      English
      Custom color
    • Placeholder string optional

      Placeholder defaults to "Pick a color".

      English
      Pick a color
    • ResetLabel string optional

      ResetLabel defaults to "Reset".

      English
      Reset
    • WhiteLabel string optional

      WhiteLabel defaults to "white".

      English
      white
  • Popover object optional

    Popover expressions. Omitted or empty fields inherit defaults.

    • TriggerLabel string optional

      TriggerLabel defaults to "Open".

      English
      Open
  • Rating object optional

    Rating expressions. Omitted or empty fields inherit defaults.

    • DissatisfiedLabel string optional

      DissatisfiedLabel defaults to "dissatisfied".

      English
      dissatisfied
    • Label string optional

      Label defaults to "Rating".

      English
      Rating
    • NeutralLabel string optional

      NeutralLabel defaults to "neutral".

      English
      neutral
    • SatisfiedLabel string optional

      SatisfiedLabel defaults to "satisfied".

      English
      satisfied
    • StarLabel string optional

      StarLabel returns the complete label for a star rating value. Values include zero for an unrated display and run through the configured maximum. In files, use {value} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      {value} stars
      Placeholder
      {value}
    • VeryDissatisfiedLabel string optional

      VeryDissatisfiedLabel defaults to "very dissatisfied".

      English
      very dissatisfied
    • VerySatisfiedLabel string optional

      VerySatisfiedLabel defaults to "very satisfied".

      English
      very satisfied
  • SchemaForm object optional

    SchemaForm expressions. Omitted or empty fields inherit defaults.

    • AddLabel string optional

      AddLabel defaults to "+ Add item".

      English
      + Add item
    • DefaultLabel string optional

      DefaultLabel returns the default-value annotation for a schema field. The argument is the field’s default value as supplied by the application. In files, use {value} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      default: {value}
      Placeholder
      {value}
    • ItemPlaceholder string optional

      ItemPlaceholder defaults to "item".

      English
      item
    • ManagedLabel string optional

      ManagedLabel defaults to "managed".

      English
      managed
    • ManagedTitle string optional

      ManagedTitle defaults to "Managed by platform — cannot override".

      English
      Managed by platform — cannot override
    • RequiredAriaLabel string optional

      RequiredAriaLabel defaults to "required".

      English
      required
  • SchemaTree object optional

    SchemaTree expressions. Omitted or empty fields inherit defaults.

    • DeprecatedLabel string optional

      DeprecatedLabel defaults to "deprecated".

      English
      deprecated
    • NullableLabel string optional

      NullableLabel defaults to "nullable".

      English
      nullable
    • OptionalLabel string optional

      OptionalLabel defaults to "optional".

      English
      optional
    • RequiredLabel string optional

      RequiredLabel defaults to "required".

      English
      required
  • Search object optional

    Search expressions. Omitted or empty fields inherit defaults.

    • EmptyText string optional

      EmptyText defaults to "No results found.".

      English
      No results found.
    • EscapeText string optional

      EscapeText defaults to "Esc".

      English
      Esc
    • Label string optional

      Label defaults to "Search".

      English
      Search
    • Placeholder string optional

      Placeholder defaults to "Search".

      English
      Search
    • ResultsAriaLabel string optional

      ResultsAriaLabel returns the results region’s accessible name from the search control’s resolved label. In files, use {label} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      {label} results
      Placeholder
      {label}
    • ShortcutText string optional

      ShortcutText defaults to "⌘ K".

      English
      ⌘ K
  • Select object optional

    Select expressions. Omitted or empty fields inherit defaults.

    • ListAriaLabel string optional

      ListAriaLabel returns the option list’s accessible name from the select control’s configured label, which may be empty. In files, use {label} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      {label} list
      Placeholder
      {label}
    • Placeholder string optional

      Placeholder defaults to "Please Select".

      English
      Please Select
  • Sidebar object optional

    Sidebar expressions. Omitted or empty fields inherit defaults.

    • ActiveLabel string optional

      ActiveLabel defaults to "active".

      English
      active
    • AriaLabel string optional

      AriaLabel defaults to "sidebar navigation".

      English
      sidebar navigation
    • SearchAriaLabel string optional

      SearchAriaLabel defaults to "Search".

      English
      Search
    • SkipLabel string optional

      SkipLabel defaults to "skip to the main content".

      English
      skip to the main content
    • TriggerLabel string optional

      TriggerLabel defaults to "Open sidebar".

      English
      Open sidebar
  • Skeleton object optional

    Skeleton expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "Loading content".

      English
      Loading content
  • SplitButton object optional

    SplitButton expressions. Omitted or empty fields inherit defaults.

    • MenuAriaLabel string optional

      MenuAriaLabel defaults to "More actions".

      English
      More actions
  • Steps object optional

    Steps expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "progress".

      English
      progress
    • CompletedLabel string optional

      CompletedLabel defaults to "completed".

      English
      completed
  • StructuredInput object optional

    StructuredInput expressions. Omitted or empty fields inherit defaults.

    • AddLabel string optional

      AddLabel defaults to "Add row".

      English
      Add row
    • RemoveAriaLabel string optional

      RemoveAriaLabel defaults to "Remove row".

      English
      Remove row
  • Table object optional

    Table expressions. Omitted or empty fields inherit defaults.

    • ActionsLabel string optional

      ActionsLabel defaults to "Actions".

      English
      Actions
    • FiltersLabel string optional

      FiltersLabel defaults to "Filters".

      English
      Filters
    • LoadMoreLabel string optional

      LoadMoreLabel defaults to "Load more".

      English
      Load more
    • LoadingText string optional

      LoadingText defaults to "Loading...".

      English
      Loading...
    • OpenRowLabel string optional

      OpenRowLabel returns the screen-reader text for opening a table row. rowID is empty when the row has no ID. In files, use {rowID} for the argument and {{ or }} for literal braces. An empty string inherits the default.

      English message
      Open row {rowID}
      Placeholder
      {rowID}
  • Tabs object optional

    Tabs expressions. Omitted or empty fields inherit defaults.

    • LoadingText string optional

      LoadingText defaults to "Loading...".

      English
      Loading...
    • OptionsAriaLabel string optional

      OptionsAriaLabel defaults to "tab options".

      English
      tab options
  • TagsList object optional

    TagsList expressions. Omitted or empty fields inherit defaults.

    • AddLabel string optional

      AddLabel defaults to "Add".

      English
      Add
    • Placeholder string optional

      Placeholder defaults to "Add a tag...".

      English
      Add a tag...
    • RemoveAriaLabel string optional

      RemoveAriaLabel defaults to "Remove tag".

      English
      Remove tag
  • TextInput object optional

    TextInput expressions. Omitted or empty fields inherit defaults.

    • SearchAriaLabel string optional

      SearchAriaLabel defaults to "search".

      English
      search
    • ShowPasswordAriaLabel string optional

      ShowPasswordAriaLabel defaults to "Show password".

      English
      Show password
  • Textarea object optional

    Textarea expressions. Omitted or empty fields inherit defaults.

    • AttachAriaLabel string optional

      AttachAriaLabel defaults to "Attach a file".

      English
      Attach a file
    • EmojiAriaLabel string optional

      EmojiAriaLabel defaults to "Emojis".

      English
      Emojis
    • SendAriaLabel string optional

      SendAriaLabel defaults to "send".

      English
      send
    • SendLabel string optional

      SendLabel defaults to "Send".

      English
      Send
    • VoiceAriaLabel string optional

      VoiceAriaLabel defaults to "Send voice".

      English
      Send voice
  • Toast object optional

    Toast expressions. Omitted or empty fields inherit defaults.

    • DismissAriaLabel string optional

      DismissAriaLabel defaults to "dismiss notification".

      English
      dismiss notification
    • DismissLabel string optional

      DismissLabel defaults to "Dismiss".

      English
      Dismiss
  • Toolbar object optional

    Toolbar expressions. Omitted or empty fields inherit defaults.

    • AriaLabel string optional

      AriaLabel defaults to "Page tools".

      English
      Page tools
  • Tooltip object optional

    Tooltip expressions. Omitted or empty fields inherit defaults.

    • TriggerLabel string optional

      TriggerLabel defaults to "Hover Me".

      English
      Hover Me