Get Locales

About

The getLocales query retrieves locale information from your store with support for pagination and detailed field access. This query is essential for:

• Displaying available language and locale options
• Building multi-language selector interfaces
• Determining text direction (LTR/RTL) for UI layout
• Retrieving locale-specific logos and branding
• Managing store language configurations
• Building locale management interfaces

The query supports cursor-based pagination and allows you to fetch all locales with full relationship access.

Arguments

Argument	Type	Required	Description
first	Int	❌ No	Number of locales to retrieve from the start (forward pagination). Max: 100.
after	String	❌ No	Cursor to start after for forward pagination.
last	Int	❌ No	Number of locales to retrieve from the end (backward pagination). Max: 100.
before	String	❌ No	Cursor to start before for backward pagination.

Possible Returns

Field	Type	Description
edges	[LocaleEdge!]!	Array of locale edges containing locales and cursors.
edges.node	Locale!	The actual locale object with id, code, name, direction, and other fields.
edges.cursor	String!	Pagination cursor for this locale. Use with after or before arguments.
pageInfo	PageInfo!	Pagination metadata object.
pageInfo.hasNextPage	Boolean!	Whether more locales exist after the current page.
pageInfo.hasPreviousPage	Boolean!	Whether locales exist before the current page.
pageInfo.startCursor	String	Cursor of the first locale on the current page.
pageInfo.endCursor	String	Cursor of the last locale on the current page.
totalCount	Int!	Total number of locales available.

Locale Fields

Field	Type	Description
id	String!	Unique identifier in format /api/shop/locales/{id}
_id	Int!	Numeric identifier for the locale
code	String!	Unique locale code (e.g., "en", "ar", "fr", "de")
name	String!	Display name of the locale (e.g., "English", "Arabic")
direction	String!	Text direction: "ltr" (left-to-right) or "rtl" (right-to-left)
logoPath	String	File path to the locale logo
logoUrl	String	Full URL to the locale logo image
createdAt	String!	Creation timestamp (ISO 8601 format)
updatedAt	String!	Last update timestamp (ISO 8601 format)

Common Use Cases

Display All Available Locales

query GetAllLocales {
  locales {
    edges {
      node {
        id
        code
        name
        direction
      }
    }
  }
}

Build Language Selector with Logos

query GetLocalesForSelector {
  locales {
    edges {
      node {
        code
        name
        logoUrl
        direction
      }
    }
  }
}

Get Locale with Complete Information

query GetLocalesWithDetails {
  locales {
    edges {
      node {
        id
        _id
        code
        name
        direction
        logoPath
        logoUrl
        createdAt
        updatedAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Get Locale Count and Pagination

query GetLocalesWithPagination($first: Int!) {
  locales(first: $first) {
    edges {
      cursor
      node {
        id
        code
        name
        direction
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Build Right-to-Left (RTL) Language List

query GetRTLLocales {
  locales {
    edges {
      node {
        code
        name
        direction
        logoUrl
      }
    }
  }
}

Error Handling

Missing Locales Configuration

{
  "data": {
    "locales": {
      "edges": [],
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": null,
        "endCursor": null
      },
      "totalCount": 0
    }
  }
}

Invalid Pagination Parameters

{
  "errors": [
    {
      "message": "Argument \"first\" must be between 1 and 100"
    }
  ]
}

Invalid Cursor

{
  "errors": [
    {
      "message": "Invalid cursor provided"
    }
  ]
}

Best Practices

1. Cache Locales - Locales change infrequently; implement client-side caching
2. Use Direction Field - Always check the direction field for proper UI layout
3. Request Only Needed Fields - Reduce payload by selecting specific fields
4. Display Logo URLs - Use logoUrl for locale-specific branding in selectors
5. Handle RTL/LTR - Use the direction field to apply appropriate CSS classes
6. Paginate When Needed - For systems with many locales, use pagination
7. Use Variables - Use GraphQL variables for dynamic locale queries

Related Resources

• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources
• Authentication Guide - Authentication and authorization
• Channels API - Store channel information