# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Internationalization API
  version: 1.0.0
extends: openapi/dotcms-internationalization-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/api/v1/system/i18n/{lang}/{rsrc}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a system i18n resource bundle
      effect: read
      questions:
      - Where do I load the translated UI strings for a system resource in a given language?
      - Can I fetch a whole i18n resource file for one locale?
      instructions:
      - text: Get system i18n resource {rsrc} in language {lang}.
        slots:
          rsrc: path.rsrc
          lang: path.lang
      - text: Load the {lang} translations for UI resource {rsrc}.
        slots:
          lang: path.lang
          rsrc: path.rsrc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{languageId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a language
      effect: write
      questions:
      - Can I change the country code on a language I already added?
      - How do I rename an existing language's display name?
      instructions:
      - text: Update language {languageId} to language code {languageCode} and country code {countryCode}.
        slots:
          languageId: path.languageId
          languageCode: requestBody.languageCode
          countryCode: requestBody.countryCode
      - text: Rename existing language {languageId} to {language} for country {country}.
        slots:
          languageId: path.languageId
          language: requestBody.language
          country: requestBody.country
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{languageId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a language
      effect: destructive
      questions:
      - How do I remove a language I no longer publish content in?
      - Can I delete a language by its ID?
      instructions:
      - text: Delete language {languageId}.
        slots:
          languageId: path.languageId
      - text: Remove language {languageId} from the system.
        slots:
          languageId: path.languageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/id/{languageid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a language by numeric ID
      effect: read
      questions:
      - Which language does a given language ID refer to?
      - Can I look up a language's code and country from its ID?
      instructions:
      - text: Get language with ID {languageid}.
        slots:
          languageid: path.languageid
      - text: Show the code and country of language ID {languageid}.
        slots:
          languageid: path.languageid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{language}/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all message keys for a language
      effect: read
      questions:
      - Can I pull every translation key and message for one language?
      - What UI message keys exist for a particular locale?
      instructions:
      - text: Get all message keys for language {language}.
        slots:
          language: path.language
      - text: Export every translated message in {language}.
        slots:
          language: path.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/_getdefault'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default language
      effect: read
      questions:
      - What is the default content language on this dotCMS instance?
      - Can I check which language is marked as the default?
      instructions:
      - text: Get the default language.
      - text: Tell me which language is set as the system default.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{languageTag}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a language by locale tag
      effect: read
      questions:
      - Can I find a configured language using a tag like en-US?
      - Is there a strict mode that only matches the exact language tag?
      instructions:
      - text: Find the language for tag {languageTag}.
        slots:
          languageTag: path.languageTag
      - text: Look up language tag {languageTag} with strict matching {strict}.
        slots:
          languageTag: path.languageTag
          strict: query.strict
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{languageTag}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a language from a locale tag
      effect: write
      questions:
      - Can I add a new language just by giving its locale tag?
      - What is the quickest way to create a language like fr-CA?
      instructions:
      - text: Create a language from tag {languageTag}.
        slots:
          languageTag: path.languageTag
      - text: Add language {languageTag} using strict tag parsing {strict}.
        slots:
          languageTag: path.languageTag
          strict: query.strict
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/iso'].get
  update:
    x-apievangelist-phrasing:
      intent: List ISO languages and countries
      effect: read
      questions:
      - Which ISO language and country codes can I choose from when adding a language?
      - Can I get the reference list of ISO languages and countries?
      instructions:
      - text: List the ISO languages and countries.
      - text: Show the ISO codes available for building a new language.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/i18n'].post
  update:
    x-apievangelist-phrasing:
      intent: Get selected i18n messages (v2)
      effect: read
      questions:
      - Can I fetch just a few translated message keys for a language and country with the v2 languages API?
      - Which v2 call returns i18n strings for specific keys?
      instructions:
      - text: Get the v2 i18n messages {messagesKey} for language {language} and country {country}.
        slots:
          messagesKey: requestBody.messagesKey
          language: requestBody.language
          country: requestBody.country
      - text: Translate keys {messagesKey} into {language} using the v2 languages endpoint.
        slots:
          messagesKey: requestBody.messagesKey
          language: requestBody.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/variables'].get
  update:
    x-apievangelist-phrasing:
      intent: List language variables
      effect: read
      questions:
      - What language variables are defined across my languages?
      - Can I include language variables that have no value in a given language?
      instructions:
      - text: List all language variables.
      - text: List language variables with renderNulls set to {renderNulls}.
        slots:
          renderNulls: query.renderNulls
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages'].get
  update:
    x-apievangelist-phrasing:
      intent: List configured languages (v2)
      effect: read
      questions:
      - Which languages are configured, and how many language variables does each have?
      - Can I list the languages a specific piece of content is available in?
      instructions:
      - text: List all configured languages from the v2 API.
      - text: List the languages for content inode {contentInode}.
        slots:
          contentInode: query.contentInode
      - text: List languages with variable counts, setting countLangVars to {countLangVars}.
        slots:
          countLangVars: query.countLangVars
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a language
      effect: write
      questions:
      - How do I add a new language with its own language and country codes?
      - What fields do I need to create a language, such as ISO code and country?
      instructions:
      - text: Create a language with code {languageCode} and country code {countryCode}.
        slots:
          languageCode: requestBody.languageCode
          countryCode: requestBody.countryCode
      - text: Add language {language} for {country} with ISO code {isoCode}.
        slots:
          language: requestBody.language
          country: requestBody.country
          isoCode: requestBody.isoCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/languages/{language}/_makedefault'].put
  update:
    x-apievangelist-phrasing:
      intent: Make a language the default
      effect: write
      questions:
      - How do I change the system default language?
      - Can I move assets over to the new default language when switching?
      instructions:
      - text: Make language {language} the default.
        slots:
          language: path.language
      - text: 'Set {language} as default and run the asset transfer job: {fireTransferAssetsJob}.'
        slots:
          language: path.language
          fireTransferAssetsJob: requestBody.fireTransferAssetsJob
      method: generated
      generated: '2026-09-26'