Label Import And Export

The ProAuth CLI can import and export labels as YAML. This is commonly used to manage translations, customer-specific wording, and environment-specific text as configuration as code.

ProAuth 3.x label files use the API-versioned YAML resource schema:

apiVersion: management.proauth.io/v2
kind: LabelBundle
metadata:
  name: account-labels
spec:
  entries:
    - contentPath: /authviews/userlogin-sign-in
      labels:
        - language: en
          fallback: true
          content: Sign in
        - language: de
          fallback: false
          content: Anmelden

Breaking change

ProAuth 3.x uses scoped label roots. Runtime lookup no longer falls back to the legacy /label or /page roots. Legacy label YAML files must be migrated before they can be imported with ProAuth 3.x.

Import Labels

Import one or more YAML files:

proauthcli label import "./labels/*.yml"

The CLI expands file globs, reads every LabelBundle, and sends the labels to the v2 label import endpoint. Large imports are uploaded in batches.

Import is create-or-update. Existing labels with the same content path and language are updated; missing labels are created.

Export Labels

Export all labels:

proauthcli label export "./exported-labels"

Filter by language:

proauthcli label export "./exported-labels" --language "de-ch"

Filter by content path prefix:

proauthcli label export "./exported-labels" --contentPath "/authviews/userlogin"

Exported files are written as LabelBundle resources and can be imported again without conversion.

Delete Labels

Delete labels by content path:

proauthcli label delete "/authviews/userlogin-sign-in"

The delete command removes the label entry identified by the provided content path.

Migrate Legacy Label YAML

Convert ProAuth 2.x label YAML files to the ProAuth 3.x schema:

proauthcli label migrate-yaml "./labels/*.yml" --outputPath "./labels-v3" --overwrite

Legacy input:

- contentPath: /label/userlogin-sign-in
  labels:
    - language: en
      fallback: true
      content: Sign in
    - language: de
      fallback: false
      content: Anmelden

Migrated output:

apiVersion: management.proauth.io/v2
kind: LabelBundle
metadata:
  name: login-labels
spec:
  entries:
    - contentPath: /authviews/userlogin-sign-in
      labels:
        - language: de
          fallback: false
          content: Anmelden
        - language: en
          fallback: true
          content: Sign in

Review the generated files before committing them. The migration keeps the label content and grouping semantics, rewrites legacy roots, and preserves culture suffixes. It does not preserve comments as a correctness guarantee.

ProAuth 3.x uses scoped label roots:

Root	Usage
/authviews	Authentication views, MFA UI, UserStore UI, email templates, invitations, questionnaires
/accountmgmt	Account Management views and validation text
/oidc	OIDC/protocol validation labels such as request-validation-error-*
/system	Generic platform labels such as model-validation-*
/adminapp	Admin App labels, replacing the old /page root

label migrate-yaml rewrites /page/... to /adminapp/.... Legacy /label/... entries are mapped by key: accountmgmt-* and account-change-password-* go to /accountmgmt, request-validation-error-* goes to /oidc, model-validation-* goes to /system, and remaining labels go to /authviews.

The path mapper preserves customer, subscription, tenant, and app path segments as well as culture suffixes. For example, /label/tenant/{id}/userlogin-title/fr becomes /authviews/tenant/{id}/userlogin-title/fr.

Schema Reference

Field	Required	Description
apiVersion	Yes	Must be management.proauth.io/v2.
kind	Yes	Must be LabelBundle.
metadata.name	No	Human-readable name for the bundle. Used for generated files and review context.
spec.entries	Yes	List of label groups.
spec.entries[].contentPath	Yes	Stable label content path without a language suffix.
spec.entries[].labels	Yes	Translations for the content path.
labels[].language	Yes	Culture code such as en, de, or de-ch.
labels[].fallback	Yes	Marks the fallback label for the content path.
labels[].content	Yes	Label text.

Content Paths And Fallbacks

A label bundle groups translations by the logical contentPath. The language is represented in the nested labels array rather than as separate YAML documents.

Use one fallback label per content path. The fallback label is used when no more specific language value is available.

Example:

spec:
  entries:
    - contentPath: /authviews/account-password-reset-title
      labels:
        - language: en
          fallback: true
          content: Reset your password
        - language: fr
          fallback: false
          content: Reinitialiser votre mot de passe

Recommended Repository Layout

For customer-managed configuration repositories, keep label files grouped by functional area or application surface:

labels/
  account.yml
  login.yml
  mail.yml
  admin-overrides.yml

This keeps review diffs small and makes it easier to import only a subset during rollout testing.

CI/CD Example

proauthcli loginservice \
  --host "https://idp.example.com" \
  --clientid "$PROAUTH_CLI_CLIENT_ID" \
  --clientsecret "$PROAUTH_CLI_CLIENT_SECRET"

proauthcli label import "./labels/*.yml"

For ProAuth 2.x to 3.x upgrades, run label migrate-yaml once, review the generated files, and then update your deployment scripts to import the migrated folder.