formbricks/packages/surveys

Overview

The @formbricks/surveys package provides a complete survey rendering system built with Preact/React. It features automated translation management through Lingo.dev.

Features

• Survey Components: Complete set of survey question types and UI components
• Internationalization: Built with i18next and react-i18next
• Type Safety: Full TypeScript support
• Testing: Comprehensive test coverage with Vitest
• Lightweight: Built with Preact for optimal bundle size
• Multi-language Support: Supports 10+ languages with automated translation generation

Architecture

File Structure

packages/surveys/
├── locales/                 # Translation files
│   ├── en.json             # Source translations (English)
│   ├── de.json             # Generated translations (German)
│   ├── fr.json             # Generated translations (French)
│   └── ...                 # Other target languages
├── i18n.json               # lingo.dev configuration
├── src/
│   ├── components/
│   │   ├── buttons/        # Survey navigation buttons
│   │   ├── general/        # Core survey components
│   │   ├── i18n/
│   │   │   └── provider.tsx # i18n provider component
│   │   ├── icons/          # Icon components
│   │   ├── questions/      # Question type components
│   │   └── wrappers/       # Layout wrappers
│   ├── lib/
│   │   ├── i18n.config.ts  # i18next configuration
│   │   ├── i18n-utils.ts   # Utility functions
│   │   └── ...             # Other utilities
│   ├── styles/             # CSS styles
│   └── types/              # TypeScript types
└── package.json

Setting Up Automated Translations

Prerequisites

• Lingo.dev API key
• Access to the Formbricks team on Lingo.dev

Step-by-Step Setup

1. Join the Formbricks Team

   • Join the Formbricks team on Lingo.dev

2. Get Your API Key

   • In the sidebar, go to Projects and open the default project
   • Navigate to the Settings tab
   • Copy the API key

3. Configure Environment Variables

   In the surveys package directory, create a .env file:

   # packages/surveys/.env
   LINGODOTDEV_API_KEY=<YOUR_API_KEY>
   

4. Generate Translations

   Run the translation generation script:

   # From the root of the repo or from within the surveys package
   pnpm run i18n:generate
   

This will execute the auto-translate script and update translation files if needed.

Development Workflow

Adding New Translation Keys

1. Update Source File: Add new keys to packages/surveys/locales/en.json
2. Generate Translations: Run pnpm run i18n:generate
3. Update Components: Use the new translation keys in your components with useTranslation hook
4. Test: Verify translations work across all supported languages

Updating Existing Translations

1. Update Target File: Update the translation keys in the target language file (packages/surveys/locales/<target-language>.json)
2. Test: Verify translations work across all supported languages
3. You don't need to run the i18n:generate command as it is only required when the source language is updated.

Adding New Languages

1. Update lingo.dev Configuration

Edit packages/surveys/i18n.json to include new target languages:

{
  "locale": {
    "source": "en",
    "targets": ["de", "it", ...otherLanguages, "new-lang"]
  }
}

2. Update i18n Configuration

Modify packages/surveys/src/lib/i18n.config.ts:

// Add new import
import newLangTranslations from "../../locales/new-lang.json";

i18n
  .use(ICU)
  .use(initReactI18next)
  .init({
    supportedLngs: ["en", "de", ...otherLanguages, "new-lang"],
    resources: {
      // ... existing resources
      "new-lang": { translation: newLangTranslations },
    },
  });

3. Generate Translation Files

Run the translation generation command:

pnpm run i18n:generate

This will create new translation files in the locales/ directory for each target language.

Scripts

• pnpm dev - Start development build
• pnpm build - Build for production
• pnpm test - Run tests
• pnpm test:coverage - Run tests with coverage
• pnpm i18n:generate - Generate translations using Lingo.dev
• pnpm lint - Lint and fix code