Phrase Strings API Reference — Locales

naftiko: 1.0.0-alpha2
info:
  label: Phrase Strings API Reference — Locales
  description: 'Phrase Strings API Reference — Locales. 7 operations. Lead operation: List locales used in account. Self-contained
    Naftiko capability covering one Phrase business surface.'
  tags:
  - Phrase
  - Locales
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    PHRASE_API_KEY: PHRASE_API_KEY
capability:
  consumes:
  - type: http
    namespace: strings-locales
    baseUri: https://api.phrase.com/v2
    description: Phrase Strings API Reference — Locales business capability. Self-contained, no shared references.
    resources:
    - name: accounts-id-locales
      path: /accounts/{id}/locales
      operations:
      - name: accountlocales
        method: GET
        description: List locales used in account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: projects-project_id-locales
      path: /projects/{project_id}/locales
      operations:
      - name: localeslist
        method: GET
        description: List locales
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: sort_by
          in: query
          type: string
          description: Sort locales. Valid options are "name_asc", "name_desc", "default_asc", "default_desc".
        - name: branch
          in: query
          type: string
          description: specify the branch to use
      - name: localecreate
        method: POST
        description: Create a locale
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: projects-project_id-locales-id
      path: /projects/{project_id}/locales/{id}
      operations:
      - name: localeshow
        method: GET
        description: Get a single locale
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: branch
          in: query
          type: string
          description: specify the branch to use
      - name: localeupdate
        method: PATCH
        description: Update a locale
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: localedelete
        method: DELETE
        description: Delete a locale
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: branch
          in: query
          type: string
          description: specify the branch to use
    - name: projects-project_id-locales-id-download
      path: /projects/{project_id}/locales/{id}/download
      operations:
      - name: localedownload
        method: GET
        description: Download a locale
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: branch
          in: query
          type: string
          description: specify the branch to use
        - name: file_format
          in: query
          type: string
          description: File format name. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364)
            for all supported file formats.
        - name: tags
          in: query
          type: string
          description: Limit results to keys tagged with a list of comma separated tag names.
        - name: tag
          in: query
          type: string
          description: Limit download to tagged keys. This parameter is deprecated. Please use the "tags" parameter instead
        - name: include_empty_translations
          in: query
          type: boolean
          description: Indicates whether keys without translations should be included in the output as well.
        - name: exclude_empty_zero_forms
          in: query
          type: boolean
          description: Indicates whether zero forms should be included when empty in pluralized keys.
        - name: include_translated_keys
          in: query
          type: boolean
          description: Include translated keys in the locale file. Use in combination with include_empty_translations to obtain
            only untranslated keys.
        - name: keep_notranslate_tags
          in: query
          type: boolean
          description: Indicates whether [NOTRANSLATE] tags should be kept.
        - name: convert_emoji
          in: query
          type: boolean
          description: 'This option is obsolete. Projects that were created on or after Nov 29th 2019 or that did not contain
            emoji by then will not require this flag any longer since '
        - name: format_options
          in: query
          type: object
          description: Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364)
            for a list of options available for
        - name: encoding
          in: query
          type: string
          description: Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".
        - name: skip_unverified_translations
          in: query
          type: boolean
          description: Indicates whether the locale file should skip all unverified translations. This parameter is deprecated
            and should be replaced with `include_unverified_translat
        - name: include_unverified_translations
          in: query
          type: boolean
          description: if set to false unverified translations are excluded
        - name: use_last_reviewed_version
          in: query
          type: boolean
          description: If set to true the last reviewed version of a translation is used. This is only available if the review
            workflow is enabled for the project.
        - name: fallback_locale_id
          in: query
          type: string
          description: If a key has no translation in the locale being downloaded, the translation in the fallback locale
            will be used.
        - name: use_locale_fallback
          in: query
          type: boolean
          description: If a key has no translation in the locale being downloaded, the translation in the fallback locale
            will be used.
        - name: source_locale_id
          in: query
          type: string
          description: Provides the source language of a corresponding job as the source language of the generated locale
            file. This parameter will be ignored unless used in combinati
        - name: translation_key_prefix
          in: query
          type: string
          description: 'Download all translation keys, and remove the specified prefix where possible. Warning: this may create
            duplicate key names if other keys share the same name af'
        - name: filter_by_prefix
          in: query
          type: boolean
          description: Only download translation keys containing the specified prefix, and remove the prefix from the generated
            file.
        - name: custom_metadata_filters
          in: query
          type: object
          description: Custom metadata filters. Provide the name of the metadata field and the value to filter by. Only keys
            with matching metadata will be included in the download.
        - name: locale_ids
          in: query
          type: array
          description: Locale IDs or locale names
        - name: updated_since
          in: query
          type: string
          description: Only include translations and keys that have been updated since the given date. The date must be in
            ISO 8601 format (e.g., `2023-01-01T00:00:00Z`).
    authentication:
      type: apikey
      key: Authorization
      value: '{{env.PHRASE_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: strings-locales-rest
    port: 8080
    description: REST adapter for Phrase Strings API Reference — Locales. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/accounts/{id}/locales
      name: accounts-id-locales
      description: REST surface for accounts-id-locales.
      operations:
      - method: GET
        name: accountlocales
        description: List locales used in account
        call: strings-locales.accountlocales
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{project-id}/locales
      name: projects-project-id-locales
      description: REST surface for projects-project_id-locales.
      operations:
      - method: GET
        name: localeslist
        description: List locales
        call: strings-locales.localeslist
        with:
          sort_by: rest.sort_by
          branch: rest.branch
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: localecreate
        description: Create a locale
        call: strings-locales.localecreate
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{project-id}/locales/{id}
      name: projects-project-id-locales-id
      description: REST surface for projects-project_id-locales-id.
      operations:
      - method: GET
        name: localeshow
        description: Get a single locale
        call: strings-locales.localeshow
        with:
          branch: rest.branch
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: localeupdate
        description: Update a locale
        call: strings-locales.localeupdate
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: localedelete
        description: Delete a locale
        call: strings-locales.localedelete
        with:
          branch: rest.branch
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{project-id}/locales/{id}/download
      name: projects-project-id-locales-id-download
      description: REST surface for projects-project_id-locales-id-download.
      operations:
      - method: GET
        name: localedownload
        description: Download a locale
        call: strings-locales.localedownload
        with:
          branch: rest.branch
          file_format: rest.file_format
          tags: rest.tags
          tag: rest.tag
          include_empty_translations: rest.include_empty_translations
          exclude_empty_zero_forms: rest.exclude_empty_zero_forms
          include_translated_keys: rest.include_translated_keys
          keep_notranslate_tags: rest.keep_notranslate_tags
          convert_emoji: rest.convert_emoji
          format_options: rest.format_options
          encoding: rest.encoding
          skip_unverified_translations: rest.skip_unverified_translations
          include_unverified_translations: rest.include_unverified_translations
          use_last_reviewed_version: rest.use_last_reviewed_version
          fallback_locale_id: rest.fallback_locale_id
          use_locale_fallback: rest.use_locale_fallback
          source_locale_id: rest.source_locale_id
          translation_key_prefix: rest.translation_key_prefix
          filter_by_prefix: rest.filter_by_prefix
          custom_metadata_filters: rest.custom_metadata_filters
          locale_ids: rest.locale_ids
          updated_since: rest.updated_since
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: strings-locales-mcp
    port: 9090
    transport: http
    description: MCP adapter for Phrase Strings API Reference — Locales. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: list-locales-used-account
      description: List locales used in account
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: strings-locales.accountlocales
      outputParameters:
      - type: object
        mapping: $.
    - name: list-locales
      description: List locales
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: strings-locales.localeslist
      with:
        sort_by: tools.sort_by
        branch: tools.branch
      outputParameters:
      - type: object
        mapping: $.
    - name: create-locale
      description: Create a locale
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: strings-locales.localecreate
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-single-locale
      description: Get a single locale
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: strings-locales.localeshow
      with:
        branch: tools.branch
      outputParameters:
      - type: object
        mapping: $.
    - name: update-locale
      description: Update a locale
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: strings-locales.localeupdate
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-locale
      description: Delete a locale
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: strings-locales.localedelete
      with:
        branch: tools.branch
      outputParameters:
      - type: object
        mapping: $.
    - name: download-locale
      description: Download a locale
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: strings-locales.localedownload
      with:
        branch: tools.branch
        file_format: tools.file_format
        tags: tools.tags
        tag: tools.tag
        include_empty_translations: tools.include_empty_translations
        exclude_empty_zero_forms: tools.exclude_empty_zero_forms
        include_translated_keys: tools.include_translated_keys
        keep_notranslate_tags: tools.keep_notranslate_tags
        convert_emoji: tools.convert_emoji
        format_options: tools.format_options
        encoding: tools.encoding
        skip_unverified_translations: tools.skip_unverified_translations
        include_unverified_translations: tools.include_unverified_translations
        use_last_reviewed_version: tools.use_last_reviewed_version
        fallback_locale_id: tools.fallback_locale_id
        use_locale_fallback: tools.use_locale_fallback
        source_locale_id: tools.source_locale_id
        translation_key_prefix: tools.translation_key_prefix
        filter_by_prefix: tools.filter_by_prefix
        custom_metadata_filters: tools.custom_metadata_filters
        locale_ids: tools.locale_ids
        updated_since: tools.updated_since
      outputParameters:
      - type: object
        mapping: $.