@better-i18n/schemas 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @better-i18n/schemas
+
+Shared validation schemas for API and frontend applications.
+
+## Structure
+
+- `src/projects/` - Project-related validation schemas
+- `src/organizations/` - Organization validation schemas  
+- `src/languages/` - Language validation schemas
+
+## Usage
+
+```typescript
+import { createProjectSchema } from "@better-i18n/schemas/projects";
+import { createOrganizationSchema } from "@better-i18n/schemas/organizations";
+
+// Use in tRPC routers
+create: protectedProcedure
+  .input(createProjectSchema)
+  .mutation(async ({ ctx, input }) => {
+    // ...
+  })
+
+// Use in TanStack Form
+const form = useForm({
+  validatorAdapter: zodValidator(),
+  validators: {
+    onChange: createProjectSchema,
+  },
+});
+```
+
+## Benefits
+
+- Single source of truth for validation
+- Type safety across API and frontend
+- DRY principle
+- Consistent error messages
+
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@better-i18n/schemas",
+  "version": "0.1.0",
+  "description": "Shared validation schemas for API and frontend",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./projects": "./src/projects/index.ts",
+    "./organizations": "./src/organizations/index.ts",
+    "./languages": "./src/languages/index.ts",
+    "./github": "./src/github.ts",
+    "./translations": "./src/translations.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@better-i18n/typescript-config": "workspace:*",
+    "typescript": "~5.9.2"
+  },
+  "license": "MIT"
+}

package/src/ai-models.ts

@@ -0,0 +1,275 @@
+/**
+ * Shared AI Model Configuration
+ * Single source of truth for all AI model definitions used across frontend and backend.
+ */
+
+// Provider types
+export type ModelProvider =
+  | "better-ai"
+  | "openai"
+  | "gemini"
+  | "claude"
+  | "openrouter";
+
+// Model categories
+export type ModelCategory =
+  | "flagship"
+  | "reasoning"
+  | "performance"
+  | "specialized"
+  | "legacy";
+
+// Icon types for models
+export type ModelIcon = "OpenAI" | "Gemini" | "Claude" | "BetterAI";
+
+// Model color configuration
+export interface ModelColors {
+  /** Background color for UI elements */
+  background: string;
+  /** Hover background color */
+  hover: string;
+  /** Icon/text color */
+  icon: string;
+}
+
+// Complete model configuration
+export interface AIModelConfig {
+  /** UI display ID (e.g., "gpt-5.2", "gemini-3-flash") */
+  id: string;
+  /** Display name for UI (e.g., "ChatGPT 5.2", "Gemini 3 Flash") */
+  name: string;
+  /** Provider identifier */
+  provider: ModelProvider;
+  /** Icon to display for this model (from lucide-react or custom) */
+  icon: "OpenAI" | "Gemini" | "Claude" | "BetterAI";
+  /** Colors for UI elements */
+  colors: ModelColors;
+  /** Actual API model ID to send to provider SDK (e.g., "gpt-5.2", "gemini-2.5-flash") */
+  apiModelId: string;
+  /** Max context window in tokens */
+  contextSize: number;
+  /** Max output tokens */
+  maxOutput: number;
+  /** Model description */
+  description: string;
+  /** Optional badge (e.g., "New", "Fast", "Default") */
+  badge?: string;
+  /** Is this the default model? */
+  isDefault?: boolean;
+  /** Release date info */
+  releaseDate?: string;
+  /** Training data cutoff */
+  trainingData?: string;
+  /** Speed score 0-100 */
+  speed?: number;
+  /** Model category */
+  category?: ModelCategory;
+  /** Whether this model requires user's own API key (not platform key) */
+  requiresUserKey?: boolean;
+}
+
+// Provider configuration (for UI)
+export interface ProviderInfo {
+  id: ModelProvider;
+  name: string;
+  brandColor: string;
+}
+
+/**
+ * All available AI models - Single Source of Truth
+ *
+ * Important: `apiModelId` is the actual model ID sent to the provider's SDK.
+ * This may differ from `id` which is used for UI/selection purposes.
+ *
+ * We keep only the best/flagship models from each provider to avoid clutter.
+ */
+export const AI_MODELS: AIModelConfig[] = [
+  // ============================================
+  // Better AI - Platform Default (Powered by Gemini 3 Flash)
+  // ============================================
+  {
+    id: "better-ai",
+    name: "Better AI",
+    provider: "better-ai",
+    icon: "BetterAI",
+    colors: {
+      background: "bg-gray-50 dark:bg-neutral-700",
+      hover: "hover:bg-gray-100 dark:hover:bg-neutral-600",
+      icon: "text-gray-700 dark:text-white",
+    },
+    apiModelId: "gemini-3-flash-preview",
+    contextSize: 1_048_576, // 1M tokens (verified from Google docs)
+    maxOutput: 65_536,
+    description:
+      "Fast and intelligent AI model powered by Gemini 3 Flash. No API key required.",
+    isDefault: true,
+    badge: "Default",
+    releaseDate: "Jan 2025",
+    trainingData: "Jan 2025",
+    speed: 95,
+    category: "flagship",
+    requiresUserKey: false,
+  },
+
+  // ============================================
+  // OpenAI Models (via OpenRouter)
+  // ============================================
+  {
+    id: "gpt-5.2",
+    name: "GPT 5.2",
+    provider: "openrouter",
+    icon: "OpenAI",
+    colors: {
+      background: "bg-gray-200 dark:bg-neutral-700",
+      hover: "hover:bg-gray-300 dark:hover:bg-neutral-600",
+      icon: "text-gray-600 dark:text-white",
+    },
+    apiModelId: "openai/gpt-5.2",
+    contextSize: 400_000, // 400K tokens (GPT-5 series standard)
+    maxOutput: 128_000,
+    description: "OpenAI's latest flagship model via OpenRouter.",
+    badge: "New",
+    releaseDate: "2025",
+    trainingData: "2025",
+    speed: 95,
+    category: "flagship",
+    requiresUserKey: false,
+  },
+  {
+    id: "gpt-5.1",
+    name: "GPT 5.1",
+    provider: "openrouter",
+    icon: "OpenAI",
+    colors: {
+      background: "bg-gray-200 dark:bg-neutral-700",
+      hover: "hover:bg-gray-300 dark:hover:bg-neutral-600",
+      icon: "text-gray-600 dark:text-white",
+    },
+    apiModelId: "openai/gpt-5.1",
+    contextSize: 400_000, // 400K tokens (GPT-5 series standard)
+    maxOutput: 128_000,
+    description: "OpenAI's capable model via OpenRouter.",
+    badge: "Fast",
+    releaseDate: "2025",
+    trainingData: "2025",
+    speed: 93,
+    category: "flagship",
+    requiresUserKey: false,
+  },
+
+  // ============================================
+  // Google Gemini Models
+  // ============================================
+  {
+    id: "gemini-3-pro",
+    name: "Gemini 3 Pro",
+    provider: "gemini",
+    icon: "Gemini",
+    colors: {
+      background: "bg-blue-50 dark:bg-blue-700",
+      hover: "hover:bg-blue-100 dark:hover:bg-blue-600",
+      icon: "text-blue-400 dark:text-blue-400",
+    },
+    apiModelId: "gemini-3-pro-preview",
+    contextSize: 1_048_576, // 1M tokens (verified from Google docs)
+    maxOutput: 65_536,
+    description: "Google's most capable model. Best for complex tasks.",
+    badge: "Pro",
+    releaseDate: "Jan 2025",
+    trainingData: "Jan 2025",
+    speed: 90,
+    category: "flagship",
+    requiresUserKey: false,
+  },
+
+  // ============================================
+  // Anthropic Claude (via OpenRouter) - Moved to bottom
+  // ============================================
+  {
+    id: "claude-4-sonnet",
+    name: "Claude Sonnet 4",
+    provider: "openrouter",
+    icon: "Claude",
+    colors: {
+      background: "bg-orange-50 dark:bg-orange-700",
+      hover: "hover:bg-orange-100 dark:hover:bg-orange-600",
+      icon: "text-orange-400 dark:text-orange-400",
+    },
+    apiModelId: "anthropic/claude-sonnet-4.5",
+    contextSize: 200_000,
+    maxOutput: 8_192,
+    description:
+      "Anthropic's flagship. Excellent reasoning and writing via OpenRouter.",
+    badge: "New",
+    releaseDate: "2025",
+    speed: 90,
+    category: "flagship",
+    requiresUserKey: false,
+  },
+];
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Get model config by ID
+ */
+export function getModelById(modelId: string): AIModelConfig | undefined {
+  return AI_MODELS.find((m) => m.id === modelId);
+}
+
+/**
+ * Get the actual API model ID for a given UI model ID
+ */
+export function getApiModelId(modelId: string): string {
+  const model = getModelById(modelId);
+  return model?.apiModelId ?? modelId;
+}
+
+/**
+ * Get provider for a model ID
+ */
+export function getModelProvider(modelId: string): ModelProvider {
+  const model = getModelById(modelId);
+  return model?.provider ?? "better-ai";
+}
+
+/**
+ * Get default model
+ */
+export function getDefaultModel(): AIModelConfig {
+  return AI_MODELS.find((m) => m.isDefault) ?? AI_MODELS[0];
+}
+
+/**
+ * Get models by provider
+ */
+export function getModelsByProvider(provider: ModelProvider): AIModelConfig[] {
+  return AI_MODELS.filter((m) => m.provider === provider);
+}
+
+/**
+ * Get models that don't require user API key (platform-provided)
+ */
+export function getPlatformModels(): AIModelConfig[] {
+  return AI_MODELS.filter((m) => !m.requiresUserKey);
+}
+
+/**
+ * Check if a model requires user's own API key
+ */
+export function modelRequiresUserKey(modelId: string): boolean {
+  const model = getModelById(modelId);
+  return model?.requiresUserKey ?? false;
+}
+
+/**
+ * Format context size for display (e.g., "128K", "2M")
+ */
+export function formatContextSize(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    return `${(tokens / 1_000_000).toFixed(0)}M`;
+  }
+  return `${(tokens / 1_000).toFixed(0)}K`;
+}

package/src/github.ts

@@ -0,0 +1,119 @@
+
+import { z } from 'zod';
+
+/**
+ * Schema for listing GitHub repositories from an installation.
+ */
+export const listRepositoriesSchema = z.object({
+  installationId: z.number(),
+  page: z.number().min(1).default(1),
+  limit: z.number().min(1).max(100).default(30),
+  type: z.enum(["all", "public", "private"]).default("all"),
+  sort: z
+    .enum(["created", "updated", "pushed", "full_name"])
+    .default("updated"),
+  direction: z.enum(["asc", "desc"]).default("desc"),
+});
+
+/**
+ * Schema for getting a specific GitHub repository.
+ */
+export const getRepositorySchema = z.object({
+  installationId: z.number(),
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+/**
+ * Schema for adding a GitHub repository to a project.
+ */
+export const addRepositorySchema = z.object({
+  projectId: z.string().uuid(),
+  installationId: z.number(),
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  path: z.string().default(""),
+  pattern: z.string().default(""),
+  format: z.enum(["JSON_FLAT", "JSON_NAMESPACED"]).default("JSON_FLAT"),
+  branch: z.string().optional(),
+  targetBranch: z.string().default("i18n-sync"),
+  autoPushToSourceBranch: z.boolean().default(false),
+});
+
+/**
+ * Schema for updating a GitHub repository.
+ */
+export const updateRepositorySchema = z.object({
+  repositoryId: z.string().uuid(),
+  path: z.string().optional(),
+  pattern: z.string().optional(),
+  format: z.enum(["JSON_FLAT", "JSON_NAMESPACED"]).optional(),
+  branch: z.string().optional(),
+  targetBranch: z.string().optional(),
+  enabled: z.boolean().optional(),
+  autoPushToSourceBranch: z.boolean().optional(),
+});
+
+/**
+ * Schema for removing a GitHub repository from a project.
+ */
+export const removeRepositorySchema = z.object({
+  repositoryId: z.string().uuid(),
+});
+
+/**
+ * Schema for syncing a GitHub repository.
+ */
+export const syncRepositorySchema = z.object({
+  repositoryId: z.string().uuid(),
+});
+
+/**
+ * Schema for GitHub OAuth callback.
+ */
+export const oauthCallbackSchema = z.object({
+  code: z.string().min(1),
+  state: z.string().optional(),
+  installation_id: z.string().optional(), // GitHub App installation ID (as string)
+});
+
+/**
+ * Schema for listing GitHub repository branches.
+ */
+export const listBranchesSchema = z.object({
+  installationId: z.number(),
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+/**
+ * Schema for getting GitHub repository tree.
+ */
+export const getTreeSchema = z.object({
+  installationId: z.number(),
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  branch: z.string().min(1),
+  path: z.string().default(""),
+});
+
+/**
+ * Schema for getting source files from a repository.
+ */
+export const getSourceFilesSchema = z.object({
+  repositoryId: z.string().uuid(),
+});
+
+/**
+ * Types for GitHub repository operations.
+ */
+export type ListRepositoriesInput = z.infer<typeof listRepositoriesSchema>;
+export type GetRepositoryInput = z.infer<typeof getRepositorySchema>;
+export type AddRepositoryInput = z.infer<typeof addRepositorySchema>;
+export type UpdateRepositoryInput = z.infer<typeof updateRepositorySchema>;
+export type RemoveRepositoryInput = z.infer<typeof removeRepositorySchema>;
+export type SyncRepositoryInput = z.infer<typeof syncRepositorySchema>;
+export type OAuthCallbackInput = z.infer<typeof oauthCallbackSchema>;
+export type ListBranchesInput = z.infer<typeof listBranchesSchema>;
+export type GetTreeInput = z.infer<typeof getTreeSchema>;
+export type GetSourceFilesInput = z.infer<typeof getSourceFilesSchema>;

package/src/index.ts

@@ -0,0 +1,8 @@
+
+export * from "./ai-models";
+export * from "./github";
+export * from "./languages/index";
+export * from "./organizations/index";
+export * from "./projects/index";
+export * from "./sync";
+export * from "./translations";

package/src/languages/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Language utilities and mappings
+ *
+ * Shared across the monorepo for consistent language handling.
+ */
+
+// Map common language codes to display names
+export const LANGUAGE_NAMES: Record<string, string> = {
+  en: "English",
+  tr: "Turkish",
+  de: "German",
+  fr: "French",
+  es: "Spanish",
+  it: "Italian",
+  pt: "Portuguese",
+  ru: "Russian",
+  zh: "Chinese",
+  ja: "Japanese",
+  ko: "Korean",
+  ar: "Arabic",
+  pl: "Polish",
+  nl: "Dutch",
+  sv: "Swedish",
+  no: "Norwegian",
+  da: "Danish",
+  fi: "Finnish",
+  cs: "Czech",
+  hu: "Hungarian",
+  ro: "Romanian",
+  uk: "Ukrainian",
+  vi: "Vietnamese",
+  th: "Thai",
+  id: "Indonesian",
+  ms: "Malay",
+  hi: "Hindi",
+  bn: "Bengali",
+  he: "Hebrew",
+  el: "Greek",
+  bg: "Bulgarian",
+  sk: "Slovak",
+  sl: "Slovenian",
+  hr: "Croatian",
+  sr: "Serbian",
+  lt: "Lithuanian",
+  lv: "Latvian",
+  et: "Estonian",
+  ca: "Catalan",
+  eu: "Basque",
+  gl: "Galician",
+};
+
+// Map common language codes to country codes for flags
+export const LANGUAGE_TO_COUNTRY: Record<string, string> = {
+  en: "gb",
+  tr: "tr",
+  de: "de",
+  fr: "fr",
+  es: "es",
+  it: "it",
+  pt: "pt",
+  ru: "ru",
+  zh: "cn",
+  ja: "jp",
+  ko: "kr",
+  ar: "sa",
+  pl: "pl",
+  nl: "nl",
+  sv: "se",
+  no: "no",
+  da: "dk",
+  fi: "fi",
+  cs: "cz",
+  hu: "hu",
+  ro: "ro",
+  uk: "ua",
+  vi: "vn",
+  th: "th",
+  id: "id",
+  ms: "my",
+  hi: "in",
+  bn: "bd",
+  he: "il",
+  el: "gr",
+  bg: "bg",
+  sk: "sk",
+  sl: "si",
+  hr: "hr",
+  sr: "rs",
+  lt: "lt",
+  lv: "lv",
+  et: "ee",
+  ca: "es-ct",
+  eu: "es-pv",
+  gl: "es-ga",
+};
+
+/**
+ * Get country code from language code for flag mapping
+ */
+export function getCountryCode(langCode: string): string {
+  const code = langCode.toLowerCase();
+  // Handle locale variants (e.g. en-US -> us)
+  if (code.includes("-")) {
+    const parts = code.split("-");
+    return parts[1].toLowerCase();
+  }
+  return LANGUAGE_TO_COUNTRY[code] || code;
+}
+
+/**
+ * Get language name from code, with fallback to uppercase code
+ */
+export function getLanguageName(code: string): string {
+  return LANGUAGE_NAMES[code.toLowerCase()] || code.toUpperCase();
+}
+
+/**
+ * Get language code from name (reverse lookup)
+ * Returns undefined if not found
+ */
+export function getLanguageCode(name: string): string | undefined {
+  const lowerName = name.toLowerCase();
+  for (const [code, langName] of Object.entries(LANGUAGE_NAMES)) {
+    if (langName.toLowerCase() === lowerName) {
+      return code;
+    }
+  }
+  return undefined;
+}

package/src/organizations/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./organization.input";
+
+

package/src/organizations/organization.input.ts

@@ -0,0 +1,23 @@
+
+import { z } from 'zod';
+
+/**
+ * Schema for creating a new organization.
+ */
+export const createOrganizationSchema = z.object({
+  name: z
+    .string()
+    .min(1, "Organization name is required")
+    .max(100, "Organization name must be less than 100 characters"),
+  slug: z
+    .string()
+    .regex(/^[a-z0-9-]+$/, "Slug can only contain lowercase letters, numbers, and hyphens")
+    .min(1, "Slug is required")
+    .max(50, "Slug must be less than 50 characters"),
+  logo: z.string().url("Invalid logo URL").optional(),
+});
+
+// Type exports
+export type CreateOrganizationInput = z.infer<typeof createOrganizationSchema>;
+
+

package/src/projects/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./project.input";
+
+

package/src/projects/project.input.ts

@@ -0,0 +1,116 @@
+
+import { z } from 'zod';
+
+/**
+ * Schema for creating a new project.
+ */
+export const createProjectSchema = z.object({
+  name: z.string().min(1, "Project name is required").max(100, "Project name must be less than 100 characters"),
+  slug: z
+    .string()
+    .regex(/^[a-z0-9-]+$/, "Slug can only contain lowercase letters, numbers, and hyphens")
+    .min(1, "Slug is required")
+    .max(50, "Slug must be less than 50 characters"),
+  sourceLanguage: z.string().length(2, "Invalid language code"),
+  organizationId: z.string().uuid("Invalid organization ID"),
+});
+
+/**
+ * Schema for updating a project.
+ */
+export const updateProjectSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+  name: z.string().min(1).max(100).optional(),
+  slug: z.string().regex(/^[a-z0-9-]+$/).optional(),
+  sourceLanguage: z.string().length(2, "Invalid language code").optional(),
+  autoTranslate: z.boolean().optional(),
+  aiSystemPrompt: z.string().max(2000, "System prompt must be less than 2000 characters").optional().nullable(),
+});
+
+/**
+ * Schema for project list query.
+ */
+export const listProjectsSchema = z.object({
+  organizationId: z.string().uuid("Invalid organization ID"),
+  page: z.number().int().positive().default(1),
+  limit: z.number().int().positive().max(100).default(20),
+  search: z.string().optional(),
+});
+
+/**
+ * Schema for getting a project by ID.
+ */
+export const getProjectSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+});
+
+/**
+ * Schema for getting a project by slug.
+ */
+export const getProjectBySlugSchema = z.object({
+  organizationId: z.string().uuid("Invalid organization ID"),
+  slug: z.string().regex(/^[a-z0-9-]+$/, "Invalid project slug"),
+});
+
+/**
+ * Schema for deleting a project.
+ */
+export const deleteProjectSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+});
+
+/**
+ * Schema for adding a target language to a project.
+ */
+export const addTargetLanguageSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+  languageCode: z.string().length(2, "Invalid language code"),
+});
+
+/**
+ * Schema for removing a target language from a project.
+ */
+export const removeTargetLanguageSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+  languageCode: z.string().length(2, "Invalid language code"),
+});
+
+/**
+ * Schema for toggling a target language's disabled state.
+ */
+export const toggleTargetLanguageSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+  languageCode: z.string().length(2, "Invalid language code"),
+  disabled: z.boolean(),
+});
+
+/**
+ * Schema for checking project slug availability within an organization.
+ */
+export const checkProjectSlugAvailabilitySchema = z.object({
+  organizationId: z.string().uuid("Invalid organization ID"),
+  slug: z.string().min(1).max(50).regex(/^[a-z0-9-]+$/, {
+    message: "Slug can only contain lowercase letters, numbers, and hyphens",
+  }),
+});
+
+/**
+ * Schema for getting project target languages.
+ */
+export const getTargetLanguagesSchema = z.object({
+  projectId: z.string().uuid("Invalid project ID"),
+});
+
+// Type exports
+export type CreateProjectInput = z.infer<typeof createProjectSchema>;
+export type UpdateProjectInput = z.infer<typeof updateProjectSchema>;
+export type ListProjectsInput = z.infer<typeof listProjectsSchema>;
+export type GetProjectInput = z.infer<typeof getProjectSchema>;
+export type GetProjectBySlugInput = z.infer<typeof getProjectBySlugSchema>;
+export type DeleteProjectInput = z.infer<typeof deleteProjectSchema>;
+export type AddTargetLanguageInput = z.infer<typeof addTargetLanguageSchema>;
+export type RemoveTargetLanguageInput = z.infer<typeof removeTargetLanguageSchema>;
+export type ToggleTargetLanguageInput = z.infer<typeof toggleTargetLanguageSchema>;
+export type GetTargetLanguagesInput = z.infer<typeof getTargetLanguagesSchema>;
+
+

package/src/sync.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+/**
+ * Schema for triggering a sync operation.
+ */
+export const triggerSyncSchema = z.object({
+  repositoryId: z.string().uuid("Invalid repository ID"),
+  projectId: z.string().uuid("Invalid project ID"),
+  /**
+   * Optional: Only sync specific translation keys (incremental sync).
+   * When provided, only these keys will be translated instead of full repository sync.
+   * This is much faster and more quota-friendly for single key additions.
+   */
+  newKeyIds: z.array(z.string().uuid()).optional(),
+  /**
+   * Optional: Type of sync job to create.
+   * - source_sync: Sync source keys from GitHub to DB (default)
+   * - publish: Generate translation files from DB and push to GitHub (create PR)
+   * - initial_import: Fast initial import of source keys only
+   * - bulk_translate: Translate existing keys without importing
+   */
+  jobType: z.enum(["source_sync", "publish", "initial_import", "bulk_translate"]).optional().default("source_sync"),
+});
+
+/**
+ * Schema for getting sync status.
+ */
+export const getSyncStatusSchema = z.object({
+  jobId: z.string().uuid("Invalid job ID"),
+});
+
+/**
+ * Schema for listing sync history.
+ */
+export const listSyncHistorySchema = z.object({
+  repositoryId: z.string().uuid("Invalid repository ID").optional(),
+  projectId: z.string().uuid("Invalid project ID").optional(),
+  page: z.number().int().positive().default(1),
+  limit: z.number().int().positive().max(100).default(20),
+});
+
+/**
+ * Schema for triggering bulk translation.
+ */
+export const triggerBulkTranslationSchema = z.object({
+  repositoryId: z.string().uuid("Invalid repository ID"),
+  projectId: z.string().uuid("Invalid project ID"),
+  /**
+   * Optional: Specific key IDs to translate.
+   * If not provided, all keys from the repository will be translated.
+   */
+  keyIds: z.array(z.string().uuid()).optional(),
+});
+
+// Type exports
+export type TriggerSyncInput = z.infer<typeof triggerSyncSchema>;
+export type GetSyncStatusInput = z.infer<typeof getSyncStatusSchema>;
+export type ListSyncHistoryInput = z.infer<typeof listSyncHistorySchema>;
+export type TriggerBulkTranslationInput = z.infer<
+  typeof triggerBulkTranslationSchema
+>;
+
+/**
+ * Schema for resyncing an existing sync job.
+ */
+export const resyncJobSchema = z.object({
+  jobId: z.string().uuid("Invalid job ID"),
+});
+
+export type ResyncJobInput = z.infer<typeof resyncJobSchema>;
+
+/**
+ * Schema for cancelling a sync job.
+ */
+export const cancelJobSchema = z.object({
+  jobId: z.string().uuid("Invalid job ID"),
+});
+
+export type CancelJobInput = z.infer<typeof cancelJobSchema>;
+

package/src/translations.ts

@@ -0,0 +1,240 @@
+import { z } from 'zod';
+
+/**
+ * Schema for listing translation keys.
+ */
+export const listTranslationKeysSchema = z.object({
+  projectId: z.string().uuid(),
+  page: z.number().min(1).default(1),
+  limit: z.number().min(1).max(5000).default(30),
+  search: z.string().optional(),
+  languageCodes: z.array(z.string()).optional(),
+  namespaces: z.array(z.string()).optional(),
+});
+
+/**
+ * Schema for getting a specific translation key.
+ */
+export const getTranslationKeySchema = z.object({
+  keyId: z.string().uuid(),
+});
+
+/**
+ * Schema for creating a translation key.
+ */
+export const createTranslationKeySchema = z.object({
+  projectId: z.string().uuid(),
+  key: z.string().min(1),
+  sourceValue: z.string().optional(),
+  description: z.string().optional(),
+  context: z.string().optional(),
+  maxLength: z.number().positive().optional(),
+});
+
+/**
+ * Schema for updating a translation key.
+ */
+export const updateTranslationKeySchema = z.object({
+  keyId: z.string().uuid(),
+  key: z.string().min(1).optional(),
+  description: z.string().optional(),
+  context: z.string().optional(),
+  maxLength: z.number().positive().optional(),
+});
+
+/**
+ * Schema for deleting a translation key.
+ */
+export const deleteTranslationKeySchema = z.object({
+  keyId: z.string().uuid(),
+});
+
+/**
+ * Schema for updating a translation.
+ * Supports both target language translations and source language edits.
+ */
+export const updateTranslationSchema = z.object({
+  keyId: z.string().uuid(),
+  languageCode: z.string().min(1),
+  value: z.string(),
+  status: z
+    .enum([
+      "draft",
+      "pending",
+      "needs_review",
+      "reviewed",
+      "approved",
+      "ai_generated",
+    ])
+    .default("approved"), // ✅ Updated status model
+  // Source language editing fields
+  isSourceLanguage: z.boolean().optional().default(false),
+  reason: z.string().optional(), // For audit trail: why source was edited
+});
+
+/**
+ * Schema for bulk updating translations.
+ * Allows updating multiple translations in a single request.
+ */
+export const bulkUpdateTranslationsSchema = z.object({
+  projectId: z.string().uuid(),
+  translations: z
+    .array(
+      z.object({
+        keyId: z.string().uuid(),
+        languageCode: z.string().min(1),
+        value: z.string(),
+        status: z
+          .enum([
+            "draft",
+            "pending",
+            "needs_review",
+            "reviewed",
+            "approved",
+            "ai_generated",
+          ])
+          .default("approved"),
+        // Source language editing: when true, updates translationKey.sourceText instead of translation table
+        isSourceLanguage: z.boolean().optional().default(false),
+      }),
+    )
+    .min(1),
+});
+
+/**
+ * Types for translation operations.
+ */
+export type ListTranslationKeysInput = z.infer<
+  typeof listTranslationKeysSchema
+>;
+export type GetTranslationKeyInput = z.infer<typeof getTranslationKeySchema>;
+export type CreateTranslationKeyInput = z.infer<
+  typeof createTranslationKeySchema
+>;
+export type UpdateTranslationKeyInput = z.infer<
+  typeof updateTranslationKeySchema
+>;
+export type DeleteTranslationKeyInput = z.infer<
+  typeof deleteTranslationKeySchema
+>;
+export type UpdateTranslationInput = z.infer<typeof updateTranslationSchema>;
+export type BulkUpdateTranslationsInput = z.infer<
+  typeof bulkUpdateTranslationsSchema
+>;
+
+/**
+ * Schema for generating AI translation suggestion.
+ */
+export const generateSuggestionSchema = z.object({
+  keyId: z.string().uuid(),
+  languageCode: z.string().min(1),
+  model: z
+    .enum([
+      "gemini-2.5-pro",
+      "gemini-2.5-flash",
+      "gemini-2.5-flash-lite",
+      "gemini-2.5-flash-lite-preview-06-17",
+      "gemini-2.0-flash",
+    ])
+    .default("gemini-2.5-flash"),
+});
+
+/**
+ * Schema for AI suggestion (simplified, uses project system prompt).
+ */
+export const aiSuggestSchema = z.object({
+  keyId: z.string().uuid(),
+  sourceText: z.string(),
+  targetLanguage: z.string().min(1),
+  projectId: z.string().uuid(),
+});
+
+/**
+ * Schema for publishing translations (changing status from draft to approved).
+ */
+export const publishTranslationsSchema = z.object({
+  projectId: z.string().uuid(),
+  translations: z
+    .array(
+      z.object({
+        keyId: z.string().uuid(),
+        languageCode: z.string().min(1),
+      }),
+    )
+    .min(1),
+});
+
+/**
+ * Schema for batch sync of translations.
+ */
+export const batchSyncTranslationsSchema = z.object({
+  projectId: z.string().uuid(),
+  translations: z
+    .array(
+      z.object({
+        keyId: z.string().uuid(),
+        languageCode: z.string().min(1),
+        value: z.string(),
+        baselineValue: z.string(), // Original value when loaded
+        status: z
+          .enum(["pending", "reviewed", "approved", "conflict", "synced"])
+          .default("pending"),
+        lastModified: z.string().datetime(), // ISO string
+      }),
+    )
+    .min(1),
+  createBaseline: z.boolean().default(true), // Whether to create new baseline after sync
+});
+
+/**
+ * Schema for conflict detection.
+ */
+export const detectConflictsSchema = z.object({
+  projectId: z.string().uuid(),
+  translations: z
+    .array(
+      z.object({
+        keyId: z.string().uuid(),
+        languageCode: z.string().min(1),
+        value: z.string(),
+        baselineValue: z.string(),
+        lastModified: z.string().datetime(),
+      }),
+    )
+    .optional(), // Optional - if not provided, will fetch from server
+});
+
+/**
+ * Schema for resolving conflicts.
+ */
+export const resolveConflictsSchema = z.object({
+  projectId: z.string().uuid(),
+  resolutions: z.array(
+    z.object({
+      keyId: z.string().uuid(),
+      languageCode: z.string().min(1),
+      resolution: z.enum(["local", "server", "merged"]),
+      mergedValue: z.string().optional(), // Required if resolution is "merged"
+    }),
+  ),
+});
+
+/**
+ * Schema for getting translation health statistics.
+ */
+export const getHealthStatsSchema = z.object({
+  projectId: z.string().uuid(),
+  repositoryId: z.string().uuid().optional(),
+});
+
+export type GenerateSuggestionInput = z.infer<typeof generateSuggestionSchema>;
+export type AiSuggestInput = z.infer<typeof aiSuggestSchema>;
+export type PublishTranslationsInput = z.infer<
+  typeof publishTranslationsSchema
+>;
+export type BatchSyncTranslationsInput = z.infer<
+  typeof batchSyncTranslationsSchema
+>;
+export type DetectConflictsInput = z.infer<typeof detectConflictsSchema>;
+export type ResolveConflictsInput = z.infer<typeof resolveConflictsSchema>;
+export type GetHealthStatsInput = z.infer<typeof getHealthStatsSchema>;