Thank you for your interest in contributing to Localce! 🎉 Localce is a privacy-first, open-source translation app. Every contribution — code, docs, bug reports, ideas — helps keep it that way.
Be respectful, constructive, and inclusive. We're all here to build something useful.
- 🐛 Report bugs via the bug report template
- ✨ Suggest features via the feature request template
- 🤖 Suggest models or languages via the model suggestion template
- 💬 Help others in Discussions
- 📖 Improve docs (README, in-app text, comments)
- 🔧 Submit code via Pull Requests
- ⭐ Star the repo — it really helps with discoverability
- Node.js ≥ 20
- npm (or pnpm/yarn — examples use npm)
- LM Studio with a translation model loaded and the local server running on
http://localhost:1234
# Fork the repo on GitHub, then:
git clone https://github.com/<your-username>/localce.git
cd localce
npm install
cp .env.local.example .env.local # if it exists, otherwise see README
npm run devOpen http://localhost:3000.
| Command | What it does |
|---|---|
npm run dev |
Start the dev server with HMR |
npm run build |
Production build (next build) |
npm run start |
Run the production build |
npm run lint |
Run ESLint (must pass for CI) |
npm test |
Run unit tests once with Vitest |
npm run test:watch |
Run Vitest in watch mode |
- Create a branch from
main:git checkout -b type/short-description # e.g. feat/italian-tone, fix/history-crash, docs/install-steps - Make your changes in small, focused commits.
- Write or update tests when you change behavior in
src/lib/**. - Run the checks locally:
npm run lint npm test npm run build - Push and open a Pull Request against
mainusing the PR template. - Address review feedback — pushes to your branch update the PR automatically.
We use Conventional Commits so Release Drafter can build changelogs automatically.
feat: add Italian to language picker
fix: prevent history crash on empty text
docs: clarify LM Studio setup steps
chore(deps): bump next to 16.1.4
ci: cache node_modules in CI
Allowed types: feat, fix, docs, style, refactor, test, chore, ci, perf, build.
- TypeScript is mandatory. Don't add
.jsfiles. - ESLint must pass (
npm run lint). - Prefer functional React components and hooks.
- Use the existing shadcn/ui components in
src/components/ui/. Add new ones via the shadcn CLI rather than hand-rolling. - Keep the design system consistent with the rest of the app (Tailwind v4,
cn()helper, Radix primitives). - Do not add dependencies that ship telemetry or phone home.
Localce's headline feature is that nothing leaves your machine. Any contribution that breaks this promise is almost certainly out of scope. Specifically:
- ❌ No third-party analytics, telemetry, or error reporting
- ❌ No remote font/CDN loading that leaks user IPs
- ❌ No "phone-home" license checks
- ✅ New outbound HTTP requests must go to a user-configurable URL only
- ✅ All translations must continue to work offline (with LM Studio on
localhost)
If a feature genuinely requires a network call (e.g. an opt-in translation-memory sync), it must be off by default and clearly disclosed in the README and in-app UI.
src/
├── app/ # Next.js App Router
│ ├── page.tsx # Main translator
│ ├── history/ # Translation history
│ ├── favorites/ # Saved translations
│ ├── settings/ # App settings
│ └── api/translate/ # Translation API route
├── components/ # Reusable React components
├── contexts/ # React contexts
├── hooks/ # Custom hooks
└── lib/ # Pure utilities (add unit tests here)
- Tests live next to the code as
*.test.tsfiles. - Framework: Vitest.
- Add tests for any new pure function in
src/lib/. - Component / integration tests are welcome but not required for small UI tweaks.
Please do not open public issues for security vulnerabilities. See SECURITY.md for the private reporting process.
By contributing, you agree that your contributions will be licensed under the MIT License.