Project Overview

TransEdit is a Next.js web application for reviewing and editing translation files (locale JSONs) in a portable, local-first workflow.

Key Features:

Upload translation files (e.g.,
```
en.json
```
and a target language JSON) to generate a
```
.transedit
```
review file.
Open a review dashboard to edit translations with autosave, undo, and snapshots.
Export updated locale JSON files after review.
Share review links via Catbox-hosted files for easy collaboration.
All operations happen locally in the browser—no server or external database required. Data is stored in IndexedDB (Dexie).
Modern UI using shadcn/ui components, lucide icons, and Tailwind CSS.

Architecture Highlights:

Sharing Mechanism: Uses Catbox (a file hosting service) to upload
```
.transedit
```
files and generate short share links (
```
/review?shareId={catbox_id}
```
). Reviewers can access shared reviews, with progress merged from local storage.
Hook-Based Logic: Complex logic is extracted into custom hooks following single responsibility (e.g.,
```
use-review-loader
```
for loading,
```
use-translations-form
```
for form management,
```
use-share-link
```
for sharing).
Async Handling: Leverages TanStack Query for data fetching (
```
useQuery
```
) and mutations (
```
useMutation
```
), with toast notifications for user feedback.
Local Persistence: IndexedDB via Dexie for storing projects, progress, and snapshots.

Component Structure

Hook Structure

Custom Hooks for Logic: Extracting complex logic into custom hooks (like usePagination, useClosePositions, usePositionModals).
Single Responsibility: Each hook should handle one specific concern or related set of functionality.
Clean API: Hooks should return a clean, well-structured object with named properties rather than arrays or complex nested structures.
Reusability: Hooks should be designed for reuse across different components when possible.
Separation from UI: Business logic should live in hooks, keeping components focused on rendering.
Use tanstack query for async functions. When ever you see isLoading, isFetching, isSuccess, isError, etc. its a sign that you should use tanstack query.
Recent Implementation: Split complex hooks into focused sub-hooks (e.g.,
```
useReview
```
decomposed into
```
use-review-loader
```
,
```
use-translations-form
```
, and
```
use-share-link
```
) to adhere to single responsibility. Use
```
useMutation
```
for async operations like share link generation, with toast notifications for user feedback.

Overall Code Style

Readability First: Code should be easy to understand at a glance, avoiding clever tricks that sacrifice clarity.
Explicit over Implicit: Prefer explicit, descriptive code over implicit or overly concise approaches.
Consistent Patterns: Following consistent patterns throughout the codebase for similar functionality.
Modular Design: Breaking down complex features into modular, composable pieces.
Avoiding Repetition: Using composition and abstraction to avoid duplicating code.
This approach results in a codebase that's more maintainable, testable, and easier for team members to understand and contribute to.

Folder Structure Rules

Page Organization

Use route groups (in parentheses) to organize related pages and shared layouts
Co-locate components, hooks, and schemas with their respective pages in dedicated folders:
- ```
_components/
```
  : UI components specific to the page
- ```
_hooks/
```
  : Custom hooks specific to the page functionality
- ```
_schema/
```
  : Zod schemas and TypeScript types for the page
- ```
_actions.ts
```
  : Server actions for the page
Keep files under 500 lines of code - if a file exceeds this limit, break it down into smaller, more focused components

Component Naming Conventions

Use
```
.server.tsx
```
suffix for server components
Use
```
.loading.tsx
```
suffix for loading state components
Name components based on their functionality, not their visual appearance
Group related component variants with consistent naming (e.g.,
```
agents-table.tsx
```
,
```
agents-table.server.tsx
```
,
```
agents-table.loading.tsx
```
)
Use kebab-case for filenames (e.g.,
```
use-create-review.ts
```
,
```
review-client.tsx
```
)

Feature Organization

Organize complex features into nested directories with their own _components, _hooks, and _schema folders
For deeply nested features (like agent proposals), maintain consistent structure at each level
Use layout.tsx files to define shared UI elements for nested routes

Internationalization

Ensure all user-facing text is wrapped in translation functions
Store translations in src/messages/{locale}.json files
Keep translation keys organized by feature/page for easier maintenance
Update all language files when adding new text

Shared Components

Place truly reusable components in the root
```
/components
```
directory
Organize UI primitives in
```
/components/ui
```
Place shared icons in
```
/components/icons
```
Use
```
/components/shared
```
for business-specific reusable components

API Routes

Organize API routes by domain/entity (e.g.,
```
/api/agents
```
,
```
/api/prices
```
)
Co-locate related schemas and utilities with their API routes
Use consistent response formats across all API endpoints

Asset Organization

Store static assets in
```
/public/assets
```
organized by type:
- ```
/public/assets/chains
```
  : Chain-specific icons
- ```
/public/assets/fonts
```
  : Custom fonts
- ```
/public/assets/icons
```
  : General icons
- ```
/public/assets/illustrations
```
  : Larger illustrations
- ```
/public/assets/images
```
  : Photos and other images

Code Organization Principles

Prefer co-location over centralization for better discoverability
Keep related code close together in the file tree
Maintain consistent patterns at each level of nesting
Split complex components into smaller pieces rather than creating large files
Use explicit naming over clever abbreviations

Project Overview

TransEdit is a Next.js web application for reviewing and editing translation files (locale JSONs) in a portable, local-first workflow.

Key Features:

Upload translation files (e.g.,
```
en.json
```
and a target language JSON) to generate a
```
.transedit
```
review file.
Open a review dashboard to edit translations with autosave, undo, and snapshots.
Export updated locale JSON files after review.
Share review links via Catbox-hosted files for easy collaboration.
All operations happen locally in the browser—no server or external database required. Data is stored in IndexedDB (Dexie).
Modern UI using shadcn/ui components, lucide icons, and Tailwind CSS.

Architecture Highlights:

Sharing Mechanism: Uses Catbox (a file hosting service) to upload
```
.transedit
```
files and generate short share links (
```
/review?shareId={catbox_id}
```
). Reviewers can access shared reviews, with progress merged from local storage.
Hook-Based Logic: Complex logic is extracted into custom hooks following single responsibility (e.g.,
```
use-review-loader
```
for loading,
```
use-translations-form
```
for form management,
```
use-share-link
```
for sharing).
Async Handling: Leverages TanStack Query for data fetching (
```
useQuery
```
) and mutations (
```
useMutation
```
), with toast notifications for user feedback.
Local Persistence: IndexedDB via Dexie for storing projects, progress, and snapshots.

Component Structure

Hook Structure

Custom Hooks for Logic: Extracting complex logic into custom hooks (like usePagination, useClosePositions, usePositionModals).
Single Responsibility: Each hook should handle one specific concern or related set of functionality.
Clean API: Hooks should return a clean, well-structured object with named properties rather than arrays or complex nested structures.
Reusability: Hooks should be designed for reuse across different components when possible.
Separation from UI: Business logic should live in hooks, keeping components focused on rendering.
Use tanstack query for async functions. When ever you see isLoading, isFetching, isSuccess, isError, etc. its a sign that you should use tanstack query.
Recent Implementation: Split complex hooks into focused sub-hooks (e.g.,
```
useReview
```
decomposed into
```
use-review-loader
```
,
```
use-translations-form
```
, and
```
use-share-link
```
) to adhere to single responsibility. Use
```
useMutation
```
for async operations like share link generation, with toast notifications for user feedback.

Overall Code Style

Readability First: Code should be easy to understand at a glance, avoiding clever tricks that sacrifice clarity.
Explicit over Implicit: Prefer explicit, descriptive code over implicit or overly concise approaches.
Consistent Patterns: Following consistent patterns throughout the codebase for similar functionality.
Modular Design: Breaking down complex features into modular, composable pieces.
Avoiding Repetition: Using composition and abstraction to avoid duplicating code.
This approach results in a codebase that's more maintainable, testable, and easier for team members to understand and contribute to.

Folder Structure Rules

Page Organization

Use route groups (in parentheses) to organize related pages and shared layouts
Co-locate components, hooks, and schemas with their respective pages in dedicated folders:
- ```
_components/
```
  : UI components specific to the page
- ```
_hooks/
```
  : Custom hooks specific to the page functionality
- ```
_schema/
```
  : Zod schemas and TypeScript types for the page
- ```
_actions.ts
```
  : Server actions for the page
Keep files under 500 lines of code - if a file exceeds this limit, break it down into smaller, more focused components

Component Naming Conventions

Use
```
.server.tsx
```
suffix for server components
Use
```
.loading.tsx
```
suffix for loading state components
Name components based on their functionality, not their visual appearance
Group related component variants with consistent naming (e.g.,
```
agents-table.tsx
```
,
```
agents-table.server.tsx
```
,
```
agents-table.loading.tsx
```
)
Use kebab-case for filenames (e.g.,
```
use-create-review.ts
```
,
```
review-client.tsx
```
)

Feature Organization

Organize complex features into nested directories with their own _components, _hooks, and _schema folders
For deeply nested features (like agent proposals), maintain consistent structure at each level
Use layout.tsx files to define shared UI elements for nested routes

Internationalization

Ensure all user-facing text is wrapped in translation functions
Store translations in src/messages/{locale}.json files
Keep translation keys organized by feature/page for easier maintenance
Update all language files when adding new text

Shared Components

Place truly reusable components in the root
```
/components
```
directory
Organize UI primitives in
```
/components/ui
```
Place shared icons in
```
/components/icons
```
Use
```
/components/shared
```
for business-specific reusable components

API Routes

Organize API routes by domain/entity (e.g.,
```
/api/agents
```
,
```
/api/prices
```
)
Co-locate related schemas and utilities with their API routes
Use consistent response formats across all API endpoints

Asset Organization

Store static assets in
```
/public/assets
```
organized by type:
- ```
/public/assets/chains
```
  : Chain-specific icons
- ```
/public/assets/fonts
```
  : Custom fonts
- ```
/public/assets/icons
```
  : General icons
- ```
/public/assets/illustrations
```
  : Larger illustrations
- ```
/public/assets/images
```
  : Photos and other images

Code Organization Principles

Prefer co-location over centralization for better discoverability
Keep related code close together in the file tree
Maintain consistent patterns at each level of nesting
Split complex components into smaller pieces rather than creating large files
Use explicit naming over clever abbreviations

Project Overview

Project Overview

Component Structure

Hook Structure

Overall Code Style

Folder Structure Rules

Page Organization

Component Naming Conventions

Feature Organization

Internationalization

Shared Components

API Routes

Asset Organization

Code Organization Principles

Related Skills

Markdown Converter

Nano Banana Pro

1password

Project Overview

Component Structure

Hook Structure

Overall Code Style

Folder Structure Rules

Page Organization

Component Naming Conventions

Feature Organization

Internationalization

Shared Components

API Routes

Asset Organization

Code Organization Principles