refactor: added JSDoc comments to exported functions in locales.ts

Author: sidhuiwnl

packages/cli/src/cli/cmd/cleanup.ts

@@ -11,9 +11,9 @@ export default new Command()
   .command("cleanup")
   .description("Remove keys from target files that do not exist in the source file")
   .helpOption("-h, --help", "Show help")
-  .option("--locale <locale>", "Clean up only the specified target locale.If not provided, processes all target locales.")
-  .option("--bucket <bucket>", " Clean up only the specified bucket type.If not provided, processes all buckets.")
-  .option("--dry-run", "Show what would be removed without actually modifying any files.")
+  .option("--locale <locale>", "Clean up only the specified target locale")
+  .option("--bucket <bucket>", " Clean up only the specified bucket type")
+  .option("--dry-run", "Show what would be removed without actually modifying any files")
   .option("--verbose", "Show detailed output including:\n" +
                       "  - List of keys that would be removed.\n" +
                       "  - Processing steps.")

packages/cli/src/cli/cmd/i18n.ts

@@ -25,12 +25,12 @@ export default new Command()
   .option("--locale <locale>", "Locale to process", (val: string, prev: string[]) => (prev ? [...prev, val] : [val]))
   .option("--bucket <bucket>", "Bucket to process", (val: string, prev: string[]) => (prev ? [...prev, val] : [val]))
   .option("--key <key>", "Key to process.Process only a specific translation key. Useful for debugging or updating a single entry.")
-  .option("--frozen", `Run in read-only mode - fails if any translations need updating.Useful for CI/CD pipelines to detect missing translations.`)
+  .option("--frozen", `Run in read-only mode - fails if any translations need updating. Useful for CI/CD pipelines to detect missing translations.`)
   .option("--force", "Ignore lockfile and process all keys, forcing a full re-translation.Use with caution as this may incur higher API costs.")
   .option("--verbose", "Show detailed output including intermediate processing data and API communication details.")
   .option("--interactive", "Enable interactive mode for reviewing and editing translations before they are applied.")
-  .option("--api-key <api-key>", "Explicitly set the API key to use.Override the default API key from settings.")
-  .option("--debug", "Pause execution at start for debugging purposes.Waits for user confirmation before proceeding.")
+  .option("--api-key <api-key>", "Explicitly set the API key to use. Override the default API key from settings.")
+  .option("--debug", "Pause execution at start for debugging purposes. Waits for user confirmation before proceeding.")
   .option("--strict", "Stop processing on first error instead of continuing with other locales/buckets.")
   .action(async function (options) {
     updateGitignore();

packages/spec/src/locales.ts

@@ -221,6 +221,19 @@ export const localeCodeSchema = Z.string().refine((value) => localeCodes.include
   message: "Invalid locale code",
 });
 
+/**
+ * Resolves a locale code to its full locale representation.
+ *
+ *  If the provided locale code is already a full locale code, it returns as is.
+ *  If the provided locale code is a short locale code, it returns the first corresponding full locale.
+ *  If the locale code is not found, it throws an error.
+ *
+ * @param {localeCodes} value - The locale code to resolve (either short or full)
+ * @return {LocaleCodeFull} The resolved full locale code
+ * @throws {Error} If the provided locale code is invalid.
+ */
+
+
 export const resolveLocaleCode = (value: LocaleCode): LocaleCodeFull => {
   const existingFullLocaleCode = Object.values(localeMap)
     .flat()
@@ -239,6 +252,15 @@ export const resolveLocaleCode = (value: LocaleCode): LocaleCodeFull => {
   throw new Error(`Invalid locale code: ${value}`);
 };
 
+
+/**
+ * Determines the delimiter used in a locale code
+ *
+ * @param {string} locale - the locale string (e.g.,"en_US","en-GB")
+ * @return { string | null} - The delimiter ("_" or "-") if found, otherwise `null`.
+ */
+
+
 export const getLocaleCodeDelimiter = (locale: string): string | null => {
   if (locale.includes("_")) {
     return "_";
@@ -249,6 +271,16 @@ export const getLocaleCodeDelimiter = (locale: string): string | null => {
   }
 };
 
+/**
+ * Replaces the delimiter in a locale string with the specified delimiter.
+ *
+ * @param {string}locale - The locale string (e.g.,"en_US", "en-GB").
+ * @param {"-" | "_" | null} [delimiter] - The new delimiter to replace the existing one.
+ * @returns {string} The locale string with the replaced delimiter, or the original locale if no delimiter is provided.
+ */
+
+
+
 export const resolveOverridenLocale = (locale: string, delimiter?: "-" | "_" | null): string => {
   if (!delimiter) {
     return locale;
@@ -262,6 +294,15 @@ export const resolveOverridenLocale = (locale: string, delimiter?: "-" | "_" | n
   return locale.replace(currentDelimiter, delimiter);
 };
 
-export function normalizeLocale(locale: string) {
+/**
+ * Normalizes a locale string by replacing underscores with hyphens
+ * and removing the "r" in certain regional codes (e.g., "fr-rCA" → "fr-CA")
+ *
+ * @param {string} locale - The locale string (e.g.,"en_US", "en-GB").
+ * @return {string} The normalized locale string.
+ */
+
+
+export const  normalizeLocale = (locale: string): string => {
   return locale.replaceAll("_", "-").replace(/([a-z]{2,3}-)r/, "$1");
 }