@adobe/spacecat-shared-utils 1.58.1 → 1.59.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-utils-v1.59.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.58.1...@adobe/spacecat-shared-utils-v1.59.0) (2025-10-09)
+
+
+### Features
+
+* Add locale detection util ([#1006](https://github.com/adobe/spacecat-shared/issues/1006)) ([cb8dcd6](https://github.com/adobe/spacecat-shared/commit/cb8dcd69e85cf673f9c791f8653e164e1e5a06d8))
+
 # [@adobe/spacecat-shared-utils-v1.58.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.58.0...@adobe/spacecat-shared-utils-v1.58.1) (2025-10-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.58.1",
+  "version": "1.59.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "exports": {
@@ -25,7 +25,7 @@
     "require": "test/setup-env.js",
     "reporter": "mocha-multi-reporters",
     "reporter-options": "configFile=.mocha-multi.json",
-    "spec": "test/*.test.js"
+    "spec": "test/**/*.test.js"
   },
   "repository": {
     "type": "git",
@@ -60,8 +60,12 @@
     "@aws-sdk/client-sqs": "3.893.0",
     "@json2csv/plainjs": "7.0.6",
     "aws-xray-sdk": "3.10.3",
+    "cheerio": "1.1.2",
     "date-fns": "4.1.0",
+    "franc-min": "6.2.0",
+    "iso-639-3": "3.0.1",
     "validator": "^13.15.15",
+    "world-countries": "5.1.0",
     "zod": "^4.1.11"
   }
 }

package/src/index.d.ts

@@ -273,3 +273,5 @@ export function isoCalendarWeekMonday(date: Date): Date;
 
 export * as llmoConfig from './llmo-config.js';
 export * as schemas from './schemas.js';
+
+export { type detectLocale } from './locale-detect/index.js';

package/src/index.js

@@ -101,4 +101,5 @@ export { determineAEMCSPageId, getPageEditUrl } from './aem-content-api-utils.js
 export * as llmoConfig from './llmo-config.js';
 export * as schemas from './schemas.js';
 
+export { detectLocale } from './locale-detect/locale-detect.js';
 export { prettifyLogForwardingConfig } from './cdn-helpers.js';

package/src/locale-detect/index.d.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+interface LocaleDetectConfig {
+  baseUrl: string;
+  headers?: object;
+  html?: string;
+}
+
+interface LocaleDetectResponse {
+  language: string;
+  region: string;
+}
+
+export function detectLocale(config: LocaleDetectConfig): Promise<LocaleDetectResponse>;

package/src/locale-detect/indicators.js

@@ -0,0 +1,201 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import worldCountries from 'world-countries';
+import { franc } from 'franc-min';
+
+import { parseLocale } from './utils.js';
+
+export function checkTld({ baseUrl }) {
+  const hostnameParts = baseUrl.hostname.split('.');
+  if (hostnameParts.length < 2) {
+    return [];
+  }
+  let tld = hostnameParts.pop();
+  tld = `.${tld.toLowerCase()}`;
+
+  const country = worldCountries.find((c) => c.tld.includes(tld));
+  if (!country) {
+    return [];
+  }
+  return [{
+    region: country.cca2.toUpperCase(),
+    type: 'tld',
+  }];
+}
+
+export function checkSubdomain({ baseUrl }) {
+  const hostnameParts = baseUrl.hostname.split('.');
+  if (hostnameParts.length < 3) {
+    return [];
+  }
+  const subdomain = hostnameParts[0];
+  if (!subdomain || subdomain === 'www' || subdomain.length < 2 || subdomain.length > 3) {
+    return [];
+  }
+  // We don't know if subdomain is language or region, try use as both
+  const locale = parseLocale(`${subdomain}_${subdomain}`);
+  if (locale) {
+    return [{ ...locale, type: 'subdomain' }];
+  }
+  return [];
+}
+
+export function checkPath({ baseUrl }) {
+  // Remove any file extension
+  const path = baseUrl.pathname.replace(/\.[^/.]+$/, '');
+
+  if (!path || path === '/') {
+    return [];
+  }
+
+  // Check for BCP 47 segment
+  const bcp47Segment = path
+    .split('/')
+    .find((s) => s.length === 5 && (s.includes('-') || s.includes('_')));
+  if (bcp47Segment) {
+    const locale = parseLocale(bcp47Segment);
+    if (locale) {
+      return [{ ...locale, type: 'path' }];
+    }
+  }
+
+  // Get all segments of length 2 or 3
+  let segments = path.split('/')
+    .map((s) => s.toLowerCase().trim())
+    .filter((s) => s.length === 2 || s.length === 3);
+
+  if (segments.length === 0) {
+    return [];
+  }
+
+  // If there are more than two segments, only consider the first two
+  if (segments.length > 2) {
+    segments = segments.slice(0, 2);
+  }
+
+  // If two segments, reverse them as we assume they are region and language
+  if (segments.length === 2) {
+    segments = segments.reverse();
+  }
+
+  const locale = parseLocale(segments.join('_'));
+  if (locale) {
+    return [{ ...locale, type: 'path' }];
+  }
+  return [];
+}
+
+export function checkHeaders({ headers }) {
+  const indicators = [];
+
+  const headerKeys = ['content-language', 'x-content-language'];
+
+  for (const headerKey of headerKeys) {
+    if (headers[headerKey]) {
+      const values = headers[headerKey].split(',').map((v) => v.trim());
+      for (const value of values) {
+        const locale = parseLocale(value);
+        if (locale) {
+          indicators.push({ ...locale, type: 'header' });
+        }
+      }
+    }
+  }
+
+  return indicators;
+}
+
+export function checkHtmlLang({ $ }) {
+  const lang = $('html').attr('lang');
+  if (!lang) {
+    return [];
+  }
+  const locale = parseLocale(lang);
+  if (locale) {
+    return [{ ...locale, type: 'html' }];
+  }
+  return [];
+}
+
+export function checkMetaTags({ $ }) {
+  const indicators = [];
+
+  const metaTagSelectors = ['meta[http-equiv="content-language"]', 'meta[property="og:locale"]'];
+
+  for (const metaTagSelector of metaTagSelectors) {
+    const metaTag = $(metaTagSelector);
+    if (metaTag && metaTag.length > 0) {
+      const content = metaTag.attr('content');
+      if (!content) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+      const values = metaTag.attr('content').split(',').map((v) => v.trim());
+      for (const value of values) {
+        const locale = parseLocale(value);
+        if (locale) {
+          indicators.push({ ...locale, type: 'metaTag' });
+        }
+      }
+    }
+  }
+
+  return indicators;
+}
+
+export function checkHrefLang({ baseUrl, $ }) {
+  const linkTags = $('link[hreflang]');
+  const matchingLinkTag = Array.from(linkTags).find((element) => {
+    const elementHref = new URL($(element).attr('href'));
+    if (!`${elementHref.hostname}${elementHref.pathname}`.includes(`${baseUrl.hostname}${baseUrl.pathname}`)) {
+      return false;
+    }
+    if ($(element).attr('hreflang').includes('default')) {
+      return false;
+    }
+    return true;
+  });
+  if (!matchingLinkTag) {
+    return [];
+  }
+  const locale = parseLocale($(matchingLinkTag).attr('hreflang'));
+  if (locale) {
+    return [{ ...locale, type: 'hreflang' }];
+  }
+  return [];
+}
+
+export function checkContentLanguage({ $ }) {
+  const metaDescription = $('meta[name="description"]').attr('content');
+  if (!metaDescription) {
+    return [];
+  }
+  const language = franc(metaDescription);
+  const locale = parseLocale(language);
+  if (locale) {
+    return [{ ...locale, type: 'content' }];
+  }
+  return [];
+}
+
+// Export all indicators as array
+export const indicators = [
+  checkTld,
+  checkSubdomain,
+  checkPath,
+  checkHeaders,
+  checkHtmlLang,
+  checkMetaTags,
+  checkHrefLang,
+  checkContentLanguage,
+];

package/src/locale-detect/locale-detect.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import * as cheerio from 'cheerio';
+
+import { hasText, isNonEmptyObject, isValidUrl } from '../functions.js';
+import { tracingFetch } from '../tracing-fetch.js';
+import { indicators } from './indicators.js';
+
+export async function detectLocale(config) {
+  const { baseUrl, indicatorFuncs = indicators } = config;
+
+  // Abort if baseUrl was not provided or cannot be parsed
+  if (!baseUrl || !isValidUrl(baseUrl)) {
+    throw new Error('Invalid baseUrl');
+  }
+  const indicatorResults = [];
+
+  const parsedBaseUrl = new URL(baseUrl);
+
+  // If not provided, fetch HTML and headers
+  let { html, headers } = config;
+  if (!hasText(config.html)) {
+    const response = await tracingFetch(baseUrl, { timeout: 5000 });
+    headers = response.headers;
+    html = await response.text();
+  } else if (!isNonEmptyObject(config.headers)) {
+    const response = await tracingFetch(baseUrl, { timeout: 5000, method: 'HEAD' });
+    headers = response.headers;
+  }
+
+  const $ = cheerio.load(html);
+
+  // Execute language detection indicators
+  for (const indicator of indicatorFuncs) {
+    const results = indicator({ baseUrl: parsedBaseUrl, headers, $ });
+    indicatorResults.push(...results);
+  }
+
+  // Derive locale from results
+  const summary = indicatorResults.reduce((acc, indicator) => {
+    if (indicator.region) {
+      acc.region[indicator.region] = (acc.region[indicator.region] || 0) + 1;
+    }
+    if (indicator.language) {
+      acc.language[indicator.language] = (acc.language[indicator.language] || 0) + 1;
+    }
+    return acc;
+  }, { region: {}, language: {} });
+  const region = Object.keys(summary.region).length > 0 ? Object.keys(summary.region).sort((a, b) => summary.region[b] - summary.region[a])[0] : 'US';
+  const language = Object.keys(summary.language).length > 0 ? Object.keys(summary.language).sort((a, b) => summary.language[b] - summary.language[a])[0] : 'en';
+
+  return {
+    region,
+    language,
+  };
+}

package/src/locale-detect/utils.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { iso6393 } from 'iso-639-3';
+import worldCountries from 'world-countries';
+
+export function parseLocale(locale) {
+  let language;
+  let region;
+
+  // If it contains - or _, split into language and region
+  if (locale.includes('-') || locale.includes('_')) {
+    [language, region] = locale.toLowerCase().split(/[-_]/);
+  } else {
+    language = locale.toLowerCase();
+  }
+
+  // Validate language
+  const lang = iso6393.find((l) => l.iso6393 === language || l.iso6391 === language);
+  if (!lang) {
+    language = null;
+  } else {
+    language = lang.iso6391;
+  }
+
+  // Validate region
+  const country = worldCountries.find(
+    (c) => c.cca2.toLowerCase() === region || c.cca3.toLowerCase() === region,
+  );
+  if (country) {
+    region = country.cca2.toUpperCase();
+  } else {
+    region = null;
+  }
+
+  if (!language && !region) {
+    return null;
+  }
+
+  const result = {};
+  if (language) {
+    result.language = language;
+  }
+  if (region) {
+    result.region = region.toUpperCase();
+  }
+  return result;
+}