feat(taxonomy): remove locale param from fetch(), bump to v5.4.0

CHANGELOG.md

@@ -1,3 +1,10 @@
+### Version: 5.4.0
+#### Date: Jul-16-2026
+Enhancement: Removed `locale?` parameter from `Taxonomy.fetch()` and `Term.fetch()` — locale is now set via the chainable `.param('locale', value)` API, consistent with other query modifiers.
+- `.param('locale', 'fr-fr').fetch()` is the correct pattern for localized taxonomy/term fetches
+- Updated all tests and the `taxonomy-demo.mjs` script to use the new pattern
+- No breaking change for calls that did not pass locale to `fetch()`
+
 ### Version: 5.3.0
 #### Date: Jul-16-2026
 Feature: Added Taxonomy Publishing support to the Content Delivery SDK via `stack.taxonomy()`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentstack/delivery-sdk",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "type": "module",
   "license": "MIT",
   "engines": {

src/taxonomy/index.ts

@@ -121,18 +121,16 @@ export class Taxonomy {
   /**
    * @method fetch
    * @memberof Taxonomy
-   * @description Fetches the taxonomy data by UID. Pass a locale code to retrieve the localized version.
-   * @param {string} [locale] - Optional locale code (e.g. 'hi-in'). Omit to retrieve the master locale.
+   * @description Fetches the taxonomy data by UID. Use param() or addParams() to pass locale or other query parameters.
    * @returns {Promise<T>}
    * @example
    * import contentstack from '@contentstack/delivery-sdk'
    *
    * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
    * const result = await stack.taxonomy('taxonomy_uid').fetch();
-   * const localized = await stack.taxonomy('taxonomy_uid').fetch('hi-in');
+   * const localized = await stack.taxonomy('taxonomy_uid').param('locale', 'hi-in').fetch();
    */
-  async fetch<T>(locale?: string): Promise<T> {
-    if (locale) this._queryParams.locale = locale;
+  async fetch<T>(): Promise<T> {
     const response = await getData(this._client, this._urlPath, { params: this._queryParams });
 
     if (response.taxonomy) return response.taxonomy as T;

src/taxonomy/term.ts

@@ -168,18 +168,16 @@ export class Term {
   /**
    * @method fetch
    * @memberof Term
-   * @description Fetches a single published term. Pass a locale code to retrieve the localized version.
-   * @param {string} [locale] - Optional locale code (e.g. 'mr-in'). Omit to retrieve the master locale.
+   * @description Fetches a single published term. Use param() or addParams() to pass locale or other query parameters.
    * @returns {Promise<T>}
    * @example
    * import contentstack from '@contentstack/delivery-sdk'
    *
    * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
    * const result = await stack.taxonomy('taxonomy_uid').term('term_uid').fetch();
-   * const localized = await stack.taxonomy('taxonomy_uid').term('term_uid').fetch('mr-in');
+   * const localized = await stack.taxonomy('taxonomy_uid').term('term_uid').param('locale', 'hi-in').fetch();
    */
-  async fetch<T>(locale?: string): Promise<T> {
-    if (locale) this._queryParams.locale = locale;
+  async fetch<T>(): Promise<T> {
     const response = await getData(this._client, this._urlPath, { params: this._queryParams });
     if (response.term) return response.term as T;
     return response;

test/api/taxonomy.spec.ts

@@ -21,21 +21,21 @@ describe('Taxonomy API test cases', () => {
     expect(result).toBeDefined();
   });
 
-  it('should give a localized taxonomy when a locale is passed to fetch', async () => {
-    const result = await makeTaxonomy(countryUsa).fetch<TTaxonomy>(locale);
+  it('should give a localized taxonomy when locale is set via param()', async () => {
+    const result = await makeTaxonomy(countryUsa).param('locale', locale).fetch<TTaxonomy>();
     expect(result).toBeDefined();
     if (result.publish_details) {
       expect(result.publish_details.locale).toBeDefined();
     }
   });
 
   it('should give a taxonomy with locale fallback when includeFallback is chained', async () => {
-    const result = await makeTaxonomy(countryUsa).includeFallback().fetch<TTaxonomy>(locale);
+    const result = await makeTaxonomy(countryUsa).param('locale', locale).includeFallback().fetch<TTaxonomy>();
     expect(result).toBeDefined();
   });
 
-  it('should give a localized taxonomy when fetch is called with locale', async () => {
-    const result = await makeTaxonomy('gadgets').fetch<TTaxonomy>('fr-fr');
+  it('should give a localized taxonomy when locale is set via param()', async () => {
+    const result = await makeTaxonomy('gadgets').param('locale', 'fr-fr').fetch<TTaxonomy>();
     expect(result).toBeDefined();
   });
 });
@@ -47,8 +47,8 @@ describe('Taxonomy API test cases - gadgets', () => {
     expect(result.uid).toBe('gadgets');
   });
 
-  it('should fetch gadgets taxonomy in fr-fr locale', async () => {
-    const result = await makeTaxonomy('gadgets').fetch<TTaxonomy>('fr-fr');
+  it('should fetch gadgets taxonomy in fr-fr locale via param()', async () => {
+    const result = await makeTaxonomy('gadgets').param('locale', 'fr-fr').fetch<TTaxonomy>();
     expect(result).toBeDefined();
     expect(result.uid).toBe('gadgets');
     expect(result.locale).toBe('fr-fr');

test/api/term.spec.ts

@@ -18,21 +18,21 @@ describe("Terms API test cases", () => {
     expect(result.updated_by).toBeDefined();
   });
 
-  it("should get a localized term when a locale is passed to fetch", async () => {
-    const result = await makeTerms("texas").fetch<TTerm>(locale);
+  it("should get a localized term when locale is set via param()", async () => {
+    const result = await makeTerms("texas").param('locale', locale).fetch<TTerm>();
     expect(result).toBeDefined();
     if (result.publish_details) {
       expect(result.publish_details.locale).toBeDefined();
     }
   });
 
   it("should get a term with locale fallback when includeFallback is chained", async () => {
-    const result = await makeTerms("texas").includeFallback().fetch<TTerm>(locale);
+    const result = await makeTerms("texas").param('locale', locale).includeFallback().fetch<TTerm>();
     expect(result).toBeDefined();
   });
 
-  it("should get a localized term when fetch is called with locale", async () => {
-    const result = await stack.taxonomy("gadgets").term("smartphone").fetch<TTerm>("fr-fr");
+  it("should get a localized term when locale is set via param()", async () => {
+    const result = await stack.taxonomy("gadgets").term("smartphone").param('locale', 'fr-fr').fetch<TTerm>();
     expect(result).toBeDefined();
   });
 
@@ -71,8 +71,8 @@ describe("Terms API test cases - gadgets taxonomy", () => {
     expect(result.taxonomy_uid).toBe("gadgets");
   });
 
-  it("should fetch smartphone term from gadgets in fr-fr locale", async () => {
-    const result = await stack.taxonomy("gadgets").term("smartphone").fetch<TTerm>("fr-fr");
+  it("should fetch smartphone term from gadgets in fr-fr locale via param()", async () => {
+    const result = await stack.taxonomy("gadgets").term("smartphone").param('locale', 'fr-fr').fetch<TTerm>();
     expect(result).toBeDefined();
     expect(result.uid).toBe("smartphone");
     expect(result.locale).toBe("fr-fr");

test/unit/taxonomy.spec.ts

@@ -54,9 +54,9 @@ describe('ta class', () => {
     await taxonomy.includeFallback().includeBranch().param('locale', 'fr-fr').fetch();
   });
 
-  it('should return localized taxonomy when fetch is called with locale', async () => {
+  it('should return localized taxonomy when param is used to set locale', async () => {
     mockClient.onGet('/taxonomies/taxonomy_testing').reply(200, taxonomyLocalizedFetchMock);
-    const response = await taxonomy.fetch('hi-in');
+    const response = await taxonomy.param('locale', 'hi-in').fetch();
     expect(response).toEqual(taxonomyLocalizedFetchMock.taxonomy);
   });
 });

test/unit/term.spec.ts

@@ -76,10 +76,10 @@ describe('Term class', () => {
     await term.param('depth', 1).addParams({ locale: 'fr-fr' }).ancestors();
   });
 
-  it('should fetch localized term when fetch is called with locale', async () => {
+  it('should fetch localized term when param is used to set locale', async () => {
     mockClient.onGet('/taxonomies/taxonomy_testing/terms/term1').reply(200, termLocalizedFetchMock);
 
-    const response = await term.fetch('hi-in');
+    const response = await term.param('locale', 'hi-in').fetch();
     expect(response).toEqual(termLocalizedFetchMock.term);
   });
 });