Resolve the page UI language once and let each ExApp fill its own Phrases.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/api.md

@@ -109,7 +109,15 @@ NextcloudIcons are SVG paths served by Nextcloud core under /core/img/. The libr
 func DialogHTML() template.HTML
 ```
 
-DialogHTML is the Dialog markup and script for an ExApp page. App navigation includes it. A page the ExApp renders itself inserts the same fragment. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.
+DialogHTML is the Dialog markup and script for an ExApp page, in English. App navigation includes the same fragment in the UI language and does not take a language argument. A page the ExApp renders itself inserts this fragment, or Credentials.DialogHTML when that page has a request. The page then calls exappDialog.message, exappDialog.confirm, or exappDialog.prompt and waits for the user's choice.
+
+### FillScript
+
+```go
+func FillScript() template.HTML
+```
+
+FillScript replaces English source after load and refreshes Fold from the visible item name. It does not parse Phrase text as HTML. App navigation includes it. A page the ExApp renders itself places Script in the head and FillScript at the end of the body.
 
 ### ParseCacheSeconds
 
@@ -275,6 +283,15 @@ type AppNavigation struct {
 	// DisableTheme skips the Nextcloud theme stylesheets. The zero value
 	// loads the active theme.
 	DisableTheme	bool
+	// Cred reads the UI language for this page from Nextcloud.
+	// The zero value leaves the page in English.
+	// The caller does not pass a language.
+	Cred	Credentials
+	// Phrases is the ExApp's set. The page script receives it.
+	// Library chrome is not included. The zero value leaves the page in English.
+	Phrases	Phrases
+	// MissingPhrase names the ExApp Phrase for MissingMessage.
+	MissingPhrase	string
 }
 ```
 
@@ -340,6 +357,22 @@ func (c Credentials) AuthHeaders() http.Header
 
 AuthHeaders returns AppAPI headers for a request to Nextcloud. The set is AA-VERSION, EX-APP-ID, EX-APP-VERSION, AUTHORIZATION-APP-API, and OCS-APIRequest. AUTHORIZATION-APP-API is base64 of UserID, a colon, and AppSecret. The method does not return an error; empty fields are sent as empty.
 
+#### Credentials.DialogHTML
+
+```go
+func (c Credentials) DialogHTML(r *http.Request) template.HTML
+```
+
+DialogHTML is the Dialog fragment in the UI language of r. A missing Requesting user or a failed read uses English. The caller does not pass a language.
+
+#### Credentials.UILanguage
+
+```go
+func (c Credentials) UILanguage(r *http.Request) string
+```
+
+UILanguage is the language of the Phrases for this request, "en" or "de". It reads the Requesting user's language from the Provisioning OCS user record and forwards the request's Accept-Language on that read. The locale field is ignored. A more specific code uses the broader language when this Library provides that language. Any other code, a missing Requesting user, or a failed read is English, and the page still renders. A second call with the request returned from a page render reuses that result.
+
 #### Credentials.WithUser
 
 ```go
@@ -399,11 +432,12 @@ type Item struct {
 	ID		string
 	Label		string
 	Icon		string
+	Phrase		string
 	Children	[]Item
 }
 ```
 
-Item is one App navigation entry. The ExApp chooses the ids and labels. Children may nest. The shell does not interpret the ids. Icon is an optional same-origin image URL. NextcloudIcons names the core SVGs.
+Item is one App navigation entry. The ExApp chooses the ids and labels. Children may nest. The shell does not interpret the ids. Icon is an optional same-origin image URL. NextcloudIcons names the core SVGs. Phrase names the ExApp Phrase for Label. The English label stays in the page until the script replaces it. Empty leaves the label as written.
 
 ### Notification
 
@@ -425,10 +459,11 @@ Notification is one Nextcloud bell for a single Recipient.
 type OCSClient struct {
 	Cred	Credentials
 	Client	*http.Client
+	Header	http.Header
 }
 ```
 
-OCSClient performs AppAPI-authenticated OCS requests with format=json.
+OCSClient performs AppAPI-authenticated OCS requests with format=json. Header is copied onto the outbound request after the AppAPI auth headers. The UI language read uses it to forward Accept-Language.
 
 #### OCSClient.Call
 
@@ -446,3 +481,53 @@ func (c OCSClient) URL(path string) string
 
 URL builds an OCS URL under /ocs/v2.php with format=json.
 
+### Phrases
+
+```go
+type Phrases struct {
+	// contains filtered or unexported fields
+}
+```
+
+Phrases is one ExApp's merged Phrase set. English is the complete set. A module set is merged with Merge; a repeated id uses the set added later. The page script receives this set. Library chrome is not included.
+
+#### Merge
+
+```go
+func Merge(sets ...Phrases) Phrases
+```
+
+Merge returns the sets combined in order. A repeated id uses the text from the set added later.
+
+#### ParsePhrases
+
+```go
+func ParsePhrases(en, de []byte) (Phrases, error)
+```
+
+ParsePhrases reads an English object and a German object.
+
+#### PhrasesFromFS
+
+```go
+func PhrasesFromFS(fsys fs.FS) (Phrases, error)
+```
+
+PhrasesFromFS reads i18n/en.json and i18n/de.json. Each file is one JSON object of id → text.
+
+#### Phrases.Script
+
+```go
+func (p Phrases) Script(lang string) template.HTML
+```
+
+Script defines exappPhrase for the page, from this set only.
+
+#### Phrases.Sentence
+
+```go
+func (p Phrases) Sentence(lang, id string, holes map[string]string) string
+```
+
+Sentence is the finished text for lang. A missing text for that language uses the English text. An id missing from English is the id. A hole with no value stays visible as {name}. The result is plain text; the caller escapes it when writing HTML.
+

docs/guide.md

@@ -335,11 +335,13 @@ Use it when the ExApp wants Nextcloud's navigation column, theme background, and
 ### Call sequence
 
 1. Fill `AppNavigation`. `Items`, `Page`, and `DefaultID` are required. `Header` and `MissingMessage` are optional.
-2. `Items` returns the tree for this request. An `Item` has an id, a label, optional children, and an optional `Icon`.
+2. `Items` returns the tree for this request. An `Item` has an id, a label, optional children, an optional `Icon`, and an optional `Phrase` id. The label is the English source. When `Phrase` is set, the page script replaces it for the UI language.
 3. Set `Icon` to a same-origin image URL, or to a field of `NextcloudIcons` (core SVGs Nextcloud already serves, such as `NextcloudIcons.Folder`).
 4. `Page` returns the HTML body for the selected id and whether that id is known.
 5. `SelectKey` defaults to `item`. Other query parameters, including a Visit folder, stay on the address.
-6. Mount `Handler` on the ExApp's page route.
+6. Set `Cred` to the ExApp's Nextcloud credentials. The shell reads the UI language once from that. The zero value leaves the page in English. Do not pass a language.
+7. Set `Phrases` to the ExApp's set. `MissingPhrase` names the Phrase for `MissingMessage`.
+8. Mount `Handler` on the ExApp's page route.
 
 A missing item renders `DefaultID`, shows `MissingMessage`, and publishes the corrected query on `data-address`. Every parent starts expanded. At 1024px and below, the tree stays hidden until the user opens it. Choosing an item, pressing Escape, or clicking outside closes it.
 
@@ -369,6 +371,25 @@ nav := gonexapp.AppNavigation{
 http.Handle("/page", nav.Handler())
 ```
 
+## UI language and Phrases
+
+### Purpose
+
+An ExApp page speaks the Requesting user's UI language. The Library resolves it once per page and writes its own chrome. The ExApp owns the Phrases of its pages and navigation items.
+
+### Call sequence
+
+1. `Credentials.UILanguage(r)` reads the Provisioning OCS user field `language` and forwards the page's `Accept-Language`. The field `locale` is ignored. `de` and `de_DE` use German. `en` and `en_GB` use English. Any other code, a missing user, or a failed read is English, and the page still renders. A later call on the same page request reuses that result.
+2. Put `i18n/en.json` and `i18n/de.json` at the project root, or beside a module. Each file is one JSON object of stable dotted id → text. Embed the directory and load it with `PhrasesFromFS`. `Merge` combines sets; a repeated id uses the set added later. CheckDNS and StalwartAdmin use only the default set.
+3. English is the complete set. A missing German text shows the English text. An unknown id shows the id. A hole is `{name}`. English and German name the same holes and may place them differently. A hole with no value stays as `{name}`. The value is plain text.
+4. Leave the English sentence in the HTML. Name the Phrase with `data-phrase` on the text, `data-phrase-placeholder`, `data-phrase-title`, or `data-phrase-aria-label`. A hole value is JSON on `data-phrase-holes`. App navigation injects `Phrases.Script` and `FillScript`. A page the ExApp renders itself puts `Script(lang)` in the head and `FillScript()` at the end of the body.
+5. A sentence the script creates calls `exappPhrase(id, holes)`. The map does not include Library chrome.
+6. An error the page displays is `Phrases.Sentence(lang, id, holes)`, the finished sentence. Escape it when writing HTML. A log line the page does not show stays English.
+
+### Errors
+
+`UILanguage` does not return an error. A failed read is English. `PhrasesFromFS` and `ParsePhrases` return an error when a file is missing or is not a JSON object of strings.
+
 ## Dialog
 
 ### Purpose
@@ -377,7 +398,7 @@ The Dialog is a modal for a message, a confirm, or a prompt. The page calls it f
 
 ### When to use it
 
-App navigation already includes the dialog. Insert `DialogHTML` on a page the ExApp renders itself. The buttons say OK and Cancel. The agreeing button's word may be replaced. The choice stays in the page.
+App navigation already includes the dialog in the UI language. Insert `DialogHTML()` on a page the ExApp renders itself when that page stays in English, or `Credentials.DialogHTML(r)` so the same read supplies the language. OK stays OK. Cancel is Abbrechen in German. A renamed agreeing button is the exact text the caller passes. The choice stays in the page.
 
 ### Call sequence