@linguanahq/cli 0.1.0 → 0.1.1

package/dist/templates/blank/tanstack-start/README.md

@@ -0,0 +1,34 @@
+# Blank
+
+A minimal starting point: the Linguana logo, a translated hello world, a language picker, and hot reload.
+
+A standalone tanstack-start app, generated from Linguana templates v0.1.0. Requires Node 22.12+ (or Bun).
+
+## Run
+
+```sh
+npm install
+npm run dev
+```
+
+You can also use pnpm, Yarn, or Bun. English, French, Spanish, and Arabic catalogs are bundled in demo mode. No Linguana API requests are made. The language cookie persists between visits. Arabic switches the document to RTL.
+
+## Connect your own project
+
+```sh
+npx @linguanahq/cli login
+npx @linguanahq/cli link
+npx @linguanahq/cli doctor
+```
+
+Linking writes nonsecret `linguana.json` and ignored `.env.local`. The account session stays outside this project. Only the public project ID, environment, API URL, and publishable key reach the browser. Build tokens never belong in `VITE_*` variables.
+
+Connected mode uses your published project catalogs and English source fallback. It does not load demo translations. Builds can upload the source manifest but do not start paid translations or publish catalogs. Review and publish translations in your dashboard. Existing project languages remain unchanged unless you pass `--locales`.
+
+To target another environment, use `linguana env pull --environment staging`, then `npm run build -- --mode staging`. Production uses `.env.production.local` and Vite's default production build mode. Configure matching private and public values on your build host; see .env.example.
+
+## Customize
+
+Start in src/App.tsx. Vite hot reload applies your edits as you save, without losing the selected language. Add a message by giving it a stable ID in src/Copy.tsx with its English text, a source fallback in src/messages.ts, and demo translations in src/demo-messages.ts.
+
+Run `npm run check-types` and `npm run build` before deploying. Deployment instructions are in DEPLOY.md. See LICENSE and ASSETS.md.

package/dist/templates/blank/tanstack-start/_gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.output/
+.nitro/
+.tanstack/
+.wrangler/
+.env
+.env.local
+.env.*.local
+.linguana/
+*.log

package/dist/templates/blank/tanstack-start/linguana.json

@@ -0,0 +1,10 @@
+{
+	"schemaVersion": 1,
+	"framework": "tanstack-start",
+	"template": "blank",
+	"templateVersion": "0.1.0",
+	"mode": "demo",
+	"apiUrl": "https://api.linguana.dev",
+	"sourceLocale": "en",
+	"defaultEnvironment": "development"
+}

package/dist/templates/blank/tanstack-start/nitro.config.ts

@@ -0,0 +1,2 @@
+import { defineConfig } from "nitro";
+export default defineConfig({ noExternals: ["tslib"] });

package/dist/templates/blank/tanstack-start/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "blank-tanstack-start",
+	"version": "0.1.0",
+	"private": true,
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"scripts": {
+		"dev": "vite --host 127.0.0.1",
+		"build": "vite build",
+		"preview": "vite preview",
+		"check-types": "tsr generate && tsc --noEmit",
+		"build:cloudflare": "NITRO_PRESET=cloudflare_module vite build",
+		"build:node": "NITRO_PRESET=node-server vite build",
+		"start": "node .output/server/index.mjs",
+		"deploy": "npm run build:cloudflare && wrangler deploy --config .output/server/wrangler.json"
+	},
+	"dependencies": {
+		"@linguanahq/catalog": "0.1.1",
+		"@linguanahq/core": "0.1.1",
+		"@linguanahq/react": "0.1.1",
+		"react": "^19.2.7",
+		"react-dom": "^19.2.7",
+		"@tanstack/react-router": "^1.170.17",
+		"@tanstack/react-start": "^1.168.27",
+		"tslib": "^2.8.1"
+	},
+	"devDependencies": {
+		"@linguanahq/vite": "0.1.1",
+		"typescript": "^6.0.0",
+		"vite": "^8.1.3",
+		"@types/node": "^24.0.0",
+		"wrangler": "^4.127.0",
+		"@types/react": "^19.2.17",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.3",
+		"nitro": "^3.0.260610-beta",
+		"@tanstack/router-cli": "^1.167.21"
+	}
+}

package/dist/templates/blank/tanstack-start/src/App.tsx

@@ -0,0 +1,72 @@
+import { useTranslation } from "@linguanahq/react";
+import { Fragment, useEffect } from "react";
+import Copy from "./Copy.tsx";
+import { demoLocales } from "./i18n";
+import { messages } from "./messages";
+
+export default function App() {
+	const runtime = useTranslation();
+	const locale = () => runtime.locale;
+	const locales = () =>
+		runtime.availableLocales.length
+			? runtime.availableLocales
+			: demoLocales.filter((item) => item.code === runtime.sourceLocale);
+	const translate = runtime.translate;
+	const changeLocale = (value: string) => void runtime.setLocale(value);
+	useEffect(() => {
+		document.documentElement.lang = runtime.locale;
+		document.documentElement.dir = runtime.locale.startsWith("ar")
+			? "rtl"
+			: "ltr";
+	}, [runtime.locale]);
+	const msg = (id: string, values?: Record<string, string | number>) =>
+		String(translate(id, messages[id] ?? id, values));
+	const value = (event: Event | { currentTarget: EventTarget | null }) =>
+		(event.currentTarget as HTMLSelectElement).value;
+
+	return (
+		<main className="hello">
+			<img
+				src="/logo.png"
+				alt={msg("logoAlt")}
+				className="hello-logo"
+				width={96}
+				height={96}
+			/>
+			<h1>
+				<Copy name="hello" />
+			</h1>
+			<p className="hello-intro">
+				<Copy name="intro" />
+			</p>
+			<label className="locale-picker">
+				<span className="sr-only">
+					<Copy name="language" />
+				</span>
+				<select
+					value={locale()}
+					aria-label={msg("language")}
+					onChange={(event) => {
+						changeLocale(value(event));
+					}}
+				>
+					{locales().map((language) => (
+						<Fragment key={language.code}>
+							<option value={language.code}>{language.nativeName}</option>
+						</Fragment>
+					))}
+				</select>
+			</label>
+			<p className="hello-hint">
+				<Copy name="hotReload" values={{ file: "src/App.tsx" }} />
+			</p>
+			<a
+				href="https://docs.linguana.dev"
+				className="hello-link"
+				rel="noreferrer"
+			>
+				<Copy name="docs" />
+			</a>
+		</main>
+	);
+}

package/dist/templates/blank/tanstack-start/src/Copy.tsx

@@ -0,0 +1,36 @@
+import { T } from "@linguanahq/react";
+export default function Copy(props: {
+	name: string;
+	values?: Record<string, string | number>;
+}) {
+	return (
+		<>
+			{props.name === "language" && (
+				<T id="language" defaultMessage="Language" values={props.values} />
+			)}
+			{props.name === "hello" && (
+				<T id="hello" defaultMessage="Hello, world!" values={props.values} />
+			)}
+			{props.name === "intro" && (
+				<T
+					id="intro"
+					defaultMessage="Your multilingual app is ready. Pick a language to see it translated."
+					values={props.values}
+				/>
+			)}
+			{props.name === "hotReload" && (
+				<T
+					id="hotReload"
+					defaultMessage="Edit {file} and save. The page updates instantly."
+					values={props.values}
+				/>
+			)}
+			{props.name === "docs" && (
+				<T id="docs" defaultMessage="Read the docs" values={props.values} />
+			)}
+			{props.name === "logoAlt" && (
+				<T id="logoAlt" defaultMessage="Linguana logo" values={props.values} />
+			)}
+		</>
+	);
+}

package/dist/templates/blank/tanstack-start/src/demo-messages.ts

@@ -0,0 +1,30 @@
+// These catalogs are only used when linguana.json selects demo mode.
+export const demoMessages = {
+	fr: {
+		language: "Langue",
+		hello: "Bonjour, le monde !",
+		intro:
+			"Votre application multilingue est prête. Choisissez une langue pour la voir traduite.",
+		hotReload:
+			"Modifiez {file} et enregistrez. La page se met à jour instantanément.",
+		docs: "Lire la documentation",
+		logoAlt: "Logo Linguana",
+	},
+	es: {
+		language: "Idioma",
+		hello: "¡Hola, mundo!",
+		intro:
+			"Tu aplicación multilingüe está lista. Elige un idioma para verla traducida.",
+		hotReload: "Edita {file} y guarda. La página se actualiza al instante.",
+		docs: "Leer la documentación",
+		logoAlt: "Logotipo de Linguana",
+	},
+	ar: {
+		language: "اللغة",
+		hello: "مرحبًا بالعالم!",
+		intro: "تطبيقك متعدد اللغات جاهز. اختر لغة لتراه مترجمًا.",
+		hotReload: "عدّل {file} واحفظه. تتحدّث الصفحة فورًا.",
+		docs: "اقرأ التوثيق",
+		logoAlt: "شعار Linguana",
+	},
+};

package/dist/templates/blank/tanstack-start/src/i18n.ts

@@ -0,0 +1,62 @@
+import { createCatalog } from "@linguanahq/catalog";
+import config from "../linguana.json";
+import { demoMessages } from "./demo-messages";
+export const demoLocales = [
+	{ code: "en", displayName: "English", nativeName: "English" },
+	{ code: "fr", displayName: "French", nativeName: "Français" },
+	{ code: "es", displayName: "Spanish", nativeName: "Español" },
+	{ code: "ar", displayName: "Arabic", nativeName: "العربية" },
+];
+export const demo = config.mode === "demo";
+export function cookieLocale(
+	cookie = typeof document === "undefined" ? "" : document.cookie,
+) {
+	try {
+		const value = decodeURIComponent(
+			cookie
+				.split(";")
+				.find((item) => item.trim().startsWith("linguana_locale="))
+				?.split("=")[1] ?? "en",
+		);
+		return /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(value) &&
+			(!demo || demoLocales.some((item) => item.code === value))
+			? value
+			: "en";
+	} catch {
+		return "en";
+	}
+}
+export const demoCatalogs = demo
+	? Object.entries(demoMessages).map(([locale, messages]) =>
+			createCatalog({
+				schemaVersion: "1.0",
+				projectId: "demo-blank",
+				environment: "development",
+				sourceLocale: "en",
+				locale,
+				manifestHash: "0".repeat(64),
+				version: 1,
+				messages,
+			}),
+		)
+	: [];
+export function optionsFor(
+	locale = cookieLocale(),
+): import("@linguanahq/core").LinguanaClientOptions {
+	return {
+		projectId: demo ? "demo-blank" : import.meta.env.VITE_LINGUANA_PROJECT_ID,
+		environment: demo
+			? "development"
+			: import.meta.env.VITE_LINGUANA_ENVIRONMENT,
+		initialLocale: locale,
+		fallbackLocale: config.sourceLocale,
+		catalogs: demoCatalogs,
+		...(demo
+			? { availableLocales: demoLocales }
+			: {
+					publishableKey: import.meta.env.VITE_LINGUANA_PUBLISHABLE_KEY,
+					catalogEndpoint: import.meta.env.VITE_LINGUANA_API_URL,
+					configEndpoint: import.meta.env.VITE_LINGUANA_API_URL,
+				}),
+	};
+}

package/dist/templates/blank/tanstack-start/src/locale-server.ts

@@ -0,0 +1,54 @@
+import {
+	createHydrationState,
+	loadCatalog,
+	loadRuntimeConfig,
+} from "@linguanahq/core";
+import { createServerFn } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import {
+	cookieLocale,
+	demo,
+	demoCatalogs,
+	demoLocales,
+	optionsFor,
+} from "./i18n";
+export const localeState = createServerFn({ method: "GET" }).handler(
+	async () => {
+		let locale = cookieLocale(getRequest().headers.get("cookie") ?? "");
+		const options = optionsFor(locale);
+		let catalogs = demoCatalogs;
+		let locales = demoLocales;
+		if (!demo) {
+			catalogs = [];
+			locales = demoLocales.filter(
+				(item) => item.code === options.fallbackLocale,
+			);
+			try {
+				const config = await loadRuntimeConfig({
+					endpoint: options.configEndpoint!,
+					projectId: options.projectId,
+					environment: options.environment,
+					publishableKey: options.publishableKey!,
+					signal: AbortSignal.timeout(5000),
+				});
+				locales = config.locales;
+				if (!locales.some((item) => item.code === locale))
+					locale = options.fallbackLocale;
+				if (locale !== options.fallbackLocale)
+					catalogs = [
+						await loadCatalog({
+							endpoint: options.catalogEndpoint!,
+							projectId: options.projectId,
+							environment: options.environment,
+							publishableKey: options.publishableKey!,
+							locale,
+							signal: AbortSignal.timeout(5000),
+						}),
+					];
+			} catch {
+				locale = options.fallbackLocale;
+			}
+		}
+		return { hydrationState: createHydrationState(locale, catalogs), locales };
+	},
+);

package/dist/templates/blank/tanstack-start/src/messages.ts

@@ -0,0 +1,10 @@
+// Source fallbacks; matching extractable literals live in Copy.tsx.
+export const messages: Record<string, string> = {
+	language: "Language",
+	hello: "Hello, world!",
+	intro:
+		"Your multilingual app is ready. Pick a language to see it translated.",
+	hotReload: "Edit {file} and save. The page updates instantly.",
+	docs: "Read the docs",
+	logoAlt: "Linguana logo",
+};

package/dist/templates/blank/tanstack-start/src/router.tsx

@@ -0,0 +1,10 @@
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+export function getRouter() {
+	return createRouter({ routeTree, scrollRestoration: true });
+}
+declare module "@tanstack/react-router" {
+	interface Register {
+		router: ReturnType<typeof getRouter>;
+	}
+}

package/dist/templates/blank/tanstack-start/src/routes/__root.tsx

@@ -0,0 +1,53 @@
+import { LocaleProvider } from "@linguanahq/react";
+import {
+	createRootRoute,
+	HeadContent,
+	Outlet,
+	Scripts,
+} from "@tanstack/react-router";
+import { optionsFor } from "../i18n";
+import { localeState } from "../locale-server";
+import styles from "../styles.css?url";
+export const Route = createRootRoute({
+	loader: () => localeState(),
+	head: () => ({
+		meta: [
+			{ charSet: "utf-8" },
+			{ name: "viewport", content: "width=device-width, initial-scale=1" },
+			{ title: "Blank" },
+			{
+				name: "description",
+				content:
+					"A minimal starting point: the Linguana logo, a translated hello world, a language picker, and hot reload.",
+			},
+		],
+		links: [
+			{ rel: "stylesheet", href: styles },
+			{ rel: "icon", href: "/favicon.ico" },
+		],
+	}),
+	component: Root,
+});
+function Root() {
+	const { hydrationState, locales } = Route.useLoaderData();
+	return (
+		<html
+			lang={hydrationState.locale}
+			dir={hydrationState.locale.startsWith("ar") ? "rtl" : "ltr"}
+		>
+			<head>
+				<HeadContent />
+			</head>
+			<body>
+				<LocaleProvider
+					{...optionsFor(hydrationState.locale)}
+					hydrationState={hydrationState}
+					availableLocales={locales}
+				>
+					<Outlet />
+				</LocaleProvider>
+				<Scripts />
+			</body>
+		</html>
+	);
+}

package/dist/templates/blank/tanstack-start/src/routes/index.tsx

@@ -0,0 +1,5 @@
+import { createFileRoute } from "@tanstack/react-router";
+import App from "../App";
+export const Route = createFileRoute("/")({
+	component: () => <App />,
+});

package/dist/templates/blank/tanstack-start/src/styles.css

@@ -0,0 +1,93 @@
+* {
+	box-sizing: border-box;
+}
+body {
+	margin: 0;
+	min-height: 100vh;
+	display: grid;
+	place-items: center;
+	background: #f7f8fb;
+	color: #14213d;
+	font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;
+	line-height: 1.6;
+}
+button,
+select {
+	font: inherit;
+}
+.hello {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 1rem;
+	max-width: 36rem;
+	padding: 3rem 1.5rem;
+	text-align: center;
+}
+.hello-logo {
+	width: 6rem;
+	height: 6rem;
+}
+.hello h1 {
+	margin: 0;
+	font-size: clamp(2.5rem, 8vw, 4rem);
+	line-height: 1.1;
+	letter-spacing: -0.02em;
+}
+.hello-intro {
+	margin: 0;
+	color: #46536b;
+	font-size: 1.125rem;
+}
+.locale-picker select {
+	min-height: 2.75rem;
+	padding: 0.5rem 2.5rem 0.5rem 1rem;
+	border: 1px solid #c9d1e0;
+	border-radius: 0.5rem;
+	background: #fff;
+	color: inherit;
+	cursor: pointer;
+}
+.locale-picker select:focus-visible,
+.hello-link:focus-visible {
+	outline: 3px solid #2f5bea;
+	outline-offset: 2px;
+}
+.hello-hint {
+	margin: 0.5rem 0 0;
+	color: #46536b;
+	font-size: 0.9375rem;
+}
+.hello-link {
+	color: #2f5bea;
+	font-weight: 600;
+	text-underline-offset: 0.2em;
+}
+.sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip: rect(0, 0, 0, 0);
+	white-space: nowrap;
+	border: 0;
+}
+@media (prefers-color-scheme: dark) {
+	body {
+		background: #0f1420;
+		color: #eef1f7;
+	}
+	.hello-intro,
+	.hello-hint {
+		color: #aab4c8;
+	}
+	.locale-picker select {
+		background: #182033;
+		border-color: #33405c;
+	}
+	.hello-link {
+		color: #8ea8ff;
+	}
+}

package/dist/templates/blank/tanstack-start/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dist/templates/blank/tanstack-start/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"moduleResolution": "Bundler",
+		"strict": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"allowImportingTsExtensions": true,
+		"resolveJsonModule": true,
+		"noEmit": true,
+		"types": ["vite/client", "node"],
+		"jsx": "react-jsx"
+	},
+	"include": [
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.vue",
+		"src/**/*.svelte",
+		"vite.config.ts"
+	]
+}

package/dist/templates/blank/tanstack-start/vite.config.ts

@@ -0,0 +1,50 @@
+import { fileURLToPath } from "node:url";
+import { linguana } from "@linguanahq/vite";
+import { react } from "@linguanahq/vite/react";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import native from "@vitejs/plugin-react";
+import { nitro } from "nitro/vite";
+import { defineConfig, loadEnv } from "vite";
+import config from "./linguana.json" with { type: "json" };
+export default defineConfig(({ mode }) => {
+	const env = { ...loadEnv(mode, process.cwd(), ""), ...process.env };
+	const connected = config.mode === "connected";
+	if (
+		connected &&
+		(!env.LINGUANA_PROJECT_ID ||
+			!env.VITE_LINGUANA_PUBLISHABLE_KEY ||
+			env.LINGUANA_PROJECT_ID !== env.VITE_LINGUANA_PROJECT_ID ||
+			env.LINGUANA_ENVIRONMENT !== env.VITE_LINGUANA_ENVIRONMENT ||
+			env.LINGUANA_API_URL !== env.VITE_LINGUANA_API_URL)
+	)
+		throw new Error(
+			"Linguana environment is incomplete or inconsistent. Run linguana env pull for this build mode.",
+		);
+	return {
+		resolve: {
+			alias: [
+				{
+					find: "tslib",
+					replacement: fileURLToPath(
+						import.meta.resolve("tslib/tslib.es6.mjs"),
+					),
+				},
+			],
+		},
+		plugins: [
+			linguana({
+				adapter: react(),
+				projectId: connected ? env.LINGUANA_PROJECT_ID! : "demo-blank",
+				environment: connected ? env.LINGUANA_ENVIRONMENT : "development",
+				sourceLocale: config.sourceLocale,
+				apiUrl: connected ? env.LINGUANA_API_URL : undefined,
+				token: connected ? env.LINGUANA_PROJECT_TOKEN : undefined,
+				upload: connected && env.LINGUANA_UPLOAD === "true",
+				translation: false,
+			}),
+			tanstackStart(),
+			nitro(),
+			native(),
+		],
+	};
+});

package/dist/templates/blank/tanstack-start/wrangler.jsonc

@@ -0,0 +1,12 @@
+{
+  "name": "linguana-demo-blank-tanstack-start",
+  "compatibility_date": "2026-10-01",
+  "main": ".output/server/index.mjs",
+  "compatibility_flags": [
+    "nodejs_compat"
+  ],
+  "assets": {
+    "directory": ".output/public",
+    "binding": "ASSETS"
+  }
+}

package/dist/templates/blank/vue/.env.example

@@ -0,0 +1,15 @@
+# Demo mode works without credentials. Connect with npx @linguanahq/cli link.
+# Copying this file alone does not enable connected mode; use linguana.json.
+# Build/server only. NEVER prefix the project token with VITE_.
+LINGUANA_PROJECT_ID=
+LINGUANA_ENVIRONMENT=development
+LINGUANA_API_URL=https://api.linguana.dev
+LINGUANA_PROJECT_TOKEN=
+LINGUANA_UPLOAD=false
+# Paid translation is disabled; this template does not enable it automatically.
+LINGUANA_TRANSLATE=false
+# Browser-safe values. A publishable key reads published catalogs only.
+VITE_LINGUANA_PROJECT_ID=
+VITE_LINGUANA_ENVIRONMENT=development
+VITE_LINGUANA_API_URL=https://api.linguana.dev
+VITE_LINGUANA_PUBLISHABLE_KEY=

package/dist/templates/blank/vue/ASSETS.md

@@ -0,0 +1 @@
+The Linguana logo and favicon in public/ are Linguana brand assets, included so the starter renders out of the box. Replace them with your own. Sample translations are MIT. No remote images, tracking pixels, or font services are used.