From ff838cf1e934e2eb22ba576ab89c50d68a601ce4 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:03:51 -0700
Subject: [PATCH] docs: add resolveCanonicalLocale standalone function
 reference

The core/functions/locales/meta.json listed resolve-canonical-locale but
the page did not exist, leaving a broken sidebar entry. Added the page,
mirroring the existing resolveAliasLocale standalone function reference.
---
 .../locales/resolve-canonical-locale.mdx      | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/en-US/core/functions/locales/resolve-canonical-locale.mdx

diff --git a/docs/en-US/core/functions/locales/resolve-canonical-locale.mdx b/docs/en-US/core/functions/locales/resolve-canonical-locale.mdx
new file mode 100644
index 00000000..e78a959a
--- /dev/null
+++ b/docs/en-US/core/functions/locales/resolve-canonical-locale.mdx
@@ -0,0 +1,67 @@
+---
+title: resolveCanonicalLocale
+description: API reference for the resolveCanonicalLocale function
+---
+
+## Overview
+
+The `resolveCanonicalLocale` function converts alias locale codes into their canonical locale codes when custom mapping is configured. This standalone function provides the same functionality as the GT class method without requiring an instance.
+
+It is the inverse operation of [`resolveAliasLocale`](/docs/core/functions/locales/resolve-alias-locale).
+
+---
+
+## Reference
+
+### Parameters
+
+<TypeTable
+  type={{
+    "locale?": {
+      type: 'string',
+      optional: true,
+    },
+    "customMapping?": {
+      type: 'CustomMapping',
+      optional: true,
+    }
+  }}
+/>
+
+### Returns
+
+`string` - The canonical locale code if mapping exists, otherwise the original locale
+
+---
+
+## Examples
+
+```typescript
+import { resolveCanonicalLocale } from 'generaltranslation';
+
+const customMapping = {
+  'simplified-chinese': { code: 'zh-CN', name: 'Simplified Chinese' },
+  'traditional-chinese': { code: 'zh-TW', name: 'Traditional Chinese' }
+};
+
+// Resolve alias to canonical
+console.log(resolveCanonicalLocale('simplified-chinese', customMapping)); // 'zh-CN'
+console.log(resolveCanonicalLocale('traditional-chinese', customMapping)); // 'zh-TW'
+
+// Non-mapped locale returns original
+console.log(resolveCanonicalLocale('es-ES', customMapping)); // 'es-ES'
+```
+---
+
+## Notes
+
+- Converts user-friendly aliases back to canonical locale codes
+- Returns the original locale if no mapping exists
+- Essential for normalizing locales before passing them to translation services
+- Works with custom locale mappings
+- Stateless function - no side effects
+
+## Next steps
+
+- Use GT class method [`resolveCanonicalLocale`](/docs/core/class/methods/locales/resolve-canonical-locale)
+- Convert back to an alias with [`resolveAliasLocale`](/docs/core/functions/locales/resolve-alias-locale)