Multi-lang Translations App

This is a BigCommerce App built using Next.js that enables merchants to translate their catalog into multiple languages per storefront. It uses:

• App Extensions to create a native editing experience within the product list
• The BigCommerce GraphQL Admin API to fetch and update catalog localization data

Todo

• Ability to translate product name and description
• Ability to translate SEO page title and meta description
• Ability to translate dropdown variant option labels
• Ability to translate custom fields
• Add check for multi-lang functionality and fail gracefully if it's not enabled
• Ability to translate non-dropdown variant option labels
• Ability to translate pre-order settings
• Ability to translate storefront details
• Ability to translate modifier option labels
• Ability to translate modifier initial / default values
• Add remove mutations for all nodes
• Improve UX of custom field editing (should use two column layout on mobile)
• Add Sentry error tracking
• Translate app strings (including API route responses and setting user locale via JWT)
• Use default locale and available locales from channel locale settings instead of constant
• Verify app extension is only added once after app is reinstalled
• Simplify multiple database support, setup, and deployment docs
• Finish manual api token support
• Streamline types across callbacks, sessions, and db functions
• Pull out Admin GraphQL client into a separate package
• Add import / export functionality

Getting Started

Environment Variables Setup

1. Copy the sample environment file:

   cp .env.sample .env.local

2. Update the following required variables in .env.local:

   • CLIENT_ID and CLIENT_SECRET: Get these from the BigCommerce Developer Portal
   • APP_ORIGIN: Your app's URL (for local development, this will be your ngrok URL)
   • JWT_KEY: A secure random string of 32+ characters
   • DATABASE_URL: Your database connection string (see Database Setup below)

Database Setup

This app uses Neon (serverless Postgres) with Drizzle ORM for database management. It's also compatible with MySQL and SQLite with a tiny change to environment variables.

Option 1: Postgres via Neon (Recommended for Production)

1. Create a Neon database through Vercel's marketplace:

   • Visit Neon on Vercel Marketplace
   • Click "Add Integration"
   • Follow the setup instructions

2. Set up your environment variables:

   # Pull environment variables from Vercel
   vercel env pull .env.local

   This will populate your .env.local file with the necessary DATABASE_URL variable.

3. Ensure DB_TYPE=postgres is set in .env.local

Option 2: SQLite (Great for Development)

1. Set your environment variables in .env.local:

   DB_TYPE=sqlite
   DATABASE_URL=sqlite:./local.db

Option 3: MySQL

1. Set your environment variables in .env:

   DB_TYPE=mysql
   DATABASE_URL=mysql://user:password@host:port/database

Database Management

After setting up your database, run these commands:

1. Install dependencies:

   npm run dev

2. Generate the database tables from the schema:

   npm run db:generate

3. Run database migrations to create the tables in your database:

   npm run db:migrate

4. (Optional) Use Drizzle Studio to manage your data:

   npm run db:studio

Run the App Locally

npm run dev

Open http://localhost:3000 with your browser to see the result.