chore: Add jsdoc to translations

Author: Ehesp

packages/translations/src/index.ts

@@ -20,8 +20,17 @@ import { type Translations } from "./types";
 export type * from "./types";
 export * from "./mapping";
 
+/** Locale identifier string. Supports BCP 47 format (e.g., "en-US") or any string. */
 export type Locale = "en-US" | `${string}-${string}` | string;
 
+/**
+ * Registers a locale with its translations and optional fallback locale.
+ *
+ * @param locale - The locale identifier (e.g., "en-US", "fr-FR").
+ * @param translations - The translation object for this locale.
+ * @param fallback - Optional fallback locale to use when a translation is missing.
+ * @returns A registered locale object.
+ */
 export function registerLocale(
  locale: Locale,
  translations: Translations,
@@ -34,10 +43,15 @@ export function registerLocale(
  };
 }
 
+/** Pre-registered English US locale with default translations. */
 export const enUs = registerLocale("en-US", enUS);
 
+/** A registered locale with its translations and optional fallback. */
 export type RegisteredLocale = {
+ /** The locale identifier. */
  locale: Locale;
+ /** The translation object for this locale. */
  translations: Translations;
+ /** Optional fallback locale to use when a translation is missing. */
  fallback?: RegisteredLocale;
 };

packages/translations/src/locales/en-us.ts

@@ -16,6 +16,7 @@
 
 import { type Translations } from "../types";
 
+/** English US (en-US) translation set with all default translations. */
 export const enUS = {
  errors: {
  userNotFound: "No account found with this email address",

packages/translations/src/mapping.ts

@@ -18,6 +18,7 @@ import { enUS } from "./locales/en-us";
 import { type RegisteredLocale } from ".";
 import type { ErrorKey, TranslationCategory, TranslationKey, TranslationSet } from "./types";
 
+/** Maps Firebase authentication error codes to translation keys. */
 export const ERROR_CODE_MAP = {
  "auth/user-not-found": "userNotFound",
  "auth/wrong-password": "wrongPassword",
@@ -48,8 +49,21 @@ export const ERROR_CODE_MAP = {
  "auth/second-factor-already-in-use": "secondFactorAlreadyInUse",
 } satisfies Record<string, ErrorKey>;
 
+/** Firebase authentication error code type. */
 export type ErrorCode = keyof typeof ERROR_CODE_MAP;
 
+/**
+ * Retrieves a translation string for a given locale, category, and key.
+ *
+ * Falls back to the locale's fallback locale or English US if the translation is not found.
+ * Supports string replacements using {placeholder} syntax.
+ *
+ * @param locale - The registered locale to get the translation from.
+ * @param category - The translation category (e.g., "errors", "labels").
+ * @param key - The translation key within the category.
+ * @param replacements - Optional object with replacement values for placeholders in the translation string.
+ * @returns The translated string, or an empty string if not found.
+ */
 export function getTranslation<T extends TranslationCategory>(
  locale: RegisteredLocale,
  category: T,

packages/translations/src/types.ts

@@ -14,103 +14,204 @@
  * limitations under the License.
  */
 
+/** Category keys for translation sets (e.g., "errors", "messages", "labels", "prompts"). */
 export type TranslationCategory = keyof Required<Translations>;
+
+/** Generic type for translation keys within a specific category. */
 export type TranslationKey<T extends TranslationCategory> = keyof Required<Translations>[T];
+
+/** Record type representing a complete set of translations for a specific category. */
 export type TranslationSet<T extends TranslationCategory> = Record<TranslationKey<T>, string>;
+
+/** Keys for error translation messages. */
 export type ErrorKey = keyof Required<Translations>["errors"];
+
+/** Keys for informational message translations. */
 export type MessageKey = keyof Required<Translations>["messages"];
+
+/** Keys for UI label translations. */
 export type LabelKey = keyof Required<Translations>["labels"];
+
+/** Keys for prompt/instruction translations. */
 export type PromptKey = keyof Required<Translations>["prompts"];
+
+/** Configuration type for translations, mapping locale identifiers to partial translation objects. */
 export type TranslationsConfig = Partial<Record<string, Partial<Translations>>>;
 
+/** Complete translations interface containing all translation categories and their keys. */
 export type Translations = {
+ /** Error message translations. */
  errors?: {
+ /** Translation for when a user is not found. */
  userNotFound?: string;
+ /** Translation for incorrect password. */
  wrongPassword?: string;
+ /** Translation for invalid email address. */
  invalidEmail?: string;
+ /** Translation for disabled user account. */
  userDisabled?: string;
+ /** Translation for unverified email address. */
  unverifiedEmail?: string;
+ /** Translation for network request failure. */
  networkRequestFailed?: string;
+ /** Translation for too many requests. */
  tooManyRequests?: string;
+ /** Translation for email already in use. */
  emailAlreadyInUse?: string;
+ /** Translation for missing verification code. */
  missingVerificationCode?: string;
+ /** Translation for invalid credentials. */
  invalidCredential?: string;
+ /** Translation for weak password. */
  weakPassword?: string;
+ /** Translation for operation not allowed. */
  operationNotAllowed?: string;
+ /** Translation for invalid phone number. */
  invalidPhoneNumber?: string;
+ /** Translation for missing phone number. */
  missingPhoneNumber?: string;
+ /** Translation for SMS quota exceeded. */
  quotaExceeded?: string;
+ /** Translation for expired verification code. */
  codeExpired?: string;
+ /** Translation for reCAPTCHA check failure. */
  captchaCheckFailed?: string;
+ /** Translation for missing verification ID. */
  missingVerificationId?: string;
+ /** Translation for missing email address. */
  missingEmail?: string;
+ /** Translation for required display name. */
  displayNameRequired?: string;
+ /** Translation for invalid action code. */
  invalidActionCode?: string;
+ /** Translation for credential already in use. */
  credentialAlreadyInUse?: string;
+ /** Translation for operation requiring recent login. */
  requiresRecentLogin?: string;
+ /** Translation for provider already linked. */
  providerAlreadyLinked?: string;
+ /** Translation for invalid verification code. */
  invalidVerificationCode?: string;
+ /** Translation for unknown error. */
  unknownError?: string;
+ /** Translation for popup closed by user. */
  popupClosed?: string;
+ /** Translation for account existing with different credential. */
  accountExistsWithDifferentCredential?: string;
+ /** Translation for second factor already in use. */
  secondFactorAlreadyInUse?: string;
  };
+ /** Informational message translations. */
  messages?: {
+ /** Translation for password reset email sent confirmation. */
  passwordResetEmailSent?: string;
+ /** Translation for sign-in link sent confirmation. */
  signInLinkSent?: string;
+ /** Translation for verification code required first. */
  verificationCodeFirst?: string;
+ /** Translation for checking email for reset instructions. */
  checkEmailForReset?: string;
+ /** Translation for "or" divider text. */
  dividerOr?: string;
+ /** Translation for terms and privacy policy notice. */
  termsAndPrivacy?: string;
+ /** Translation for MFA SMS assertion prompt message. */
  mfaSmsAssertionPrompt?: string;
  };
+ /** UI label translations. */
  labels?: {
+ /** Translation for email address label. */
  emailAddress?: string;
+ /** Translation for password label. */
  password?: string;
+ /** Translation for display name label. */
  displayName?: string;
+ /** Translation for forgot password link. */
  forgotPassword?: string;
+ /** Translation for sign up button/link. */
  signUp?: string;
+ /** Translation for sign in button/link. */
  signIn?: string;
+ /** Translation for reset password button. */
  resetPassword?: string;
+ /** Translation for create account button. */
  createAccount?: string;
+ /** Translation for back to sign in link. */
  backToSignIn?: string;
+ /** Translation for sign in with phone button. */
  signInWithPhone?: string;
+ /** Translation for phone number label. */
  phoneNumber?: string;
+ /** Translation for verification code label. */
  verificationCode?: string;
+ /** Translation for send code button. */
  sendCode?: string;
+ /** Translation for verify code button. */
  verifyCode?: string;
+ /** Translation for sign in with Google button. */
  signInWithGoogle?: string;
+ /** Translation for sign in with Facebook button. */
  signInWithFacebook?: string;
+ /** Translation for sign in with Apple button. */
  signInWithApple?: string;
+ /** Translation for sign in with Twitter/X button. */
  signInWithTwitter?: string;
+ /** Translation for sign in with Microsoft button. */
  signInWithMicrosoft?: string;
+ /** Translation for sign in with GitHub button. */
  signInWithGitHub?: string;
+ /** Translation for sign in with email link button. */
  signInWithEmailLink?: string;
+ /** Translation for send sign-in link button. */
  sendSignInLink?: string;
+ /** Translation for terms of service link. */
  termsOfService?: string;
+ /** Translation for privacy policy link. */
  privacyPolicy?: string;
+ /** Translation for resend code button. */
  resendCode?: string;
+ /** Translation for sending state text. */
  sending?: string;
+ /** Translation for multi-factor enrollment label. */
  multiFactorEnrollment?: string;
+ /** Translation for multi-factor assertion label. */
  multiFactorAssertion?: string;
+ /** Translation for TOTP verification label. */
  mfaTotpVerification?: string;
+ /** Translation for SMS verification label. */
  mfaSmsVerification?: string;
+ /** Translation for generate QR code button. */
  generateQrCode?: string;
  };
+ /** Prompt and instruction translations. */
  prompts?: {
+ /** Translation for "don't have an account" prompt. */
  noAccount?: string;
+ /** Translation for "already have an account" prompt. */
  haveAccount?: string;
+ /** Translation for enter email to reset password prompt. */
  enterEmailToReset?: string;
+ /** Translation for sign in to account prompt. */
  signInToAccount?: string;
+ /** Translation for enter details to create account prompt. */
  enterDetailsToCreate?: string;
+ /** Translation for SMS verification code prompt. */
  smsVerificationPrompt?: string;
+ /** Translation for enter phone number prompt. */
  enterPhoneNumber?: string;
+ /** Translation for enter verification code prompt. */
  enterVerificationCode?: string;
+ /** Translation for enter email for link prompt. */
  enterEmailForLink?: string;
+ /** Translation for MFA enrollment prompt. */
  mfaEnrollmentPrompt?: string;
+ /** Translation for MFA assertion prompt. */
  mfaAssertionPrompt?: string;
+ /** Translation for MFA assertion factor selection prompt. */
  mfaAssertionFactorPrompt?: string;
+ /** Translation for TOTP QR code prompt. */
  mfaTotpQrCodePrompt?: string;
+ /** Translation for TOTP enrollment verification prompt. */
  mfaTotpEnrollmentVerificationPrompt?: string;
  };
 };