Quick Locale Ai Documentation

1. Overview

Quick Locale Ai revolutionizes the software localization (i18n) process by creating a direct, intelligent bridge between your Atlassian Confluence documentation and your development codebase. It empowers Product Owners, PMs, and Technical Writers to manage all UI text and translations from a centralized Confluence page, while providing developers with real-time, automated updates to locale files.

The core problem Quick Locale Ai solves is the inefficient, error-prone manual synchronization of text between documentation and code. By automating this, teams can significantly reduce development time, minimize errors, and accelerate the launch of multilingual products.

2. Key Features

• 📄Centralized Content Management: Confluence becomes the single source of truth for all UI text and translations.
• 🤖AI-Powered Analysis & Assistance:
  • Intelligently identifies text for localization from Confluence pages.
  • Automatically generates unique localization keys.
  • Optionally provides AI-driven draft translations to kickstart your localization efforts.
• 🔄Real-Time Synchronization: Changes made in the Confluence localization table are instantly reflected in your project's locale files.
• 💻Flexible Developer Integration:
  • VS Code Extension: Offers hot-reloading for a seamless local development experience.
  • Live URL / HTTP Backend: Allows applications to fetch the latest locales on demand, ideal for production environments.
• ✨Streamlined Workflow: Reduces manual copy-pasting, minimizes communication overhead, and frees up developer resources.
• 🛡️Consistency & Accuracy: Ensures UI text is consistent across documentation, development, and production.

3. Getting Started

Setting up Quick Locale Ai involves configuring the Confluence app and then choosing an integration method for your development team.

3.1. Confluence App Setup

1. Install the App: Install "Quick Locale Ai" from the Atlassian Marketplace into your Confluence instance.
2. Configure a Project:
   • Navigate to the Confluence page where you want to manage your locales.
   • Activate Quick Locale Ai for that page (usually via a macro or page settings, refer to the in-app guide).
   • Define your target locales (e.g., `en`, `es`, `fr`, `ja`).
   • The app will generate a unique Project Key (API Key). Keep this key secure; it will be needed for developer integration.
3. Start Adding Content: Once set up, Quick Locale Ai will guide you on how to structure your text in a table for localization. The app will then generate a comment or section on the page with the localization table.

3.2. Developer Integration

Once the Confluence app is configured and you have your Project Key, developers can integrate Quick Locale Ai into their workflow using one of two primary methods:

• VS Code Extension: For local development with real-time file synchronization and hot-reloading. (See Section 5)
• Live URL (HTTP Backend): For fetching locales directly in production or server-side applications. (See Section 6)

Both methods require a configuration file in your project, typically named quicklocale.json.

Creating quicklocale.json

In the root of your development project, create a file named quicklocale.json with the following structure:

{"key": "YOUR_PROJECT_KEY_FROM_CONFLUENCE", "locale_directory": "public/locales", "locales": ["en", "es", "fr", "ja"]}

• key: Replace with the Project Key obtained from the Confluence app setup.
• locale_directory: The relative path within your project where locale files (e.g., `en.json`, `es.json`) should be stored. Adjust this to match your project structure (e.g., src/locales, assets/i18n).
• locales: An array of the locale codes configured in Confluence for this project. This should match what you set up in the Confluence app.

4. How to Use Quick Locale Ai

4.1. Managing Locales in Confluence

The primary interface for managing all UI text and translations is the localization table generated by Quick Locale Ai on your designated Confluence page.

• Adding New Text: Add a new row to the table. Provide the source text in your primary language. Quick Locale Ai will automatically generate a unique key for this text.
• Translating Text: Fill in the translations for each target locale in the corresponding columns of the table. If AI translation is enabled, initial drafts may be provided.
• Editing Text: Simply edit the text directly within the table cells.
• Deleting Text: Remove the row from the table.

Any changes saved to this table in Confluence are automatically processed by Quick Locale Ai and pushed to the connected development environments or live URLs.

4.2. Developer Workflow

Developers primarily interact with the output of Quick Locale Ai:

• VS Code Extension Users: Locale files in the configured locale_directory will update automatically. If your development server supports hot-reloading for these file types, UI changes will appear instantly.
• Live URL Users: Your application will fetch the latest locale files when it initializes or as needed, ensuring it always uses the most up-to-date content.

Developers should reference the auto-generated keys from the locale files in their application's UI components.

4.3. The Golden Rule: Edit in Confluence Only!

5. VS Code Extension Details

The Quick Locale Ai VS Code Extension is recommended for local development.

Setup:

1. Ensure you have created the quicklocale.json configuration file in your project root as described in Section 3.2.
2. Install the "Quick Locale Ai" extension from the Visual Studio Marketplace.
3. Reload VS Code if prompted.

Features:

• Real-Time File Sync: Automatically updates files in your locale_directory when changes are made in Confluence.
• Hot-Reload Friendly: Works seamlessly with development servers that support hot-reloading.
• Status Bar Indicator: Provides visual feedback on the connection and sync status.
• Read-Only Protection (Optional): May prevent direct edits to managed locale files to enforce the "Golden Rule".

Refer to the VS Code extension's marketplace page for the most up-to-date details and specific commands it might offer (e.g., manual resync).

6. Live URL (HTTP Backend) Integration

This method is ideal for production environments or applications that need to fetch locales dynamically.

Setup:

1. You will need the Project Key from your Confluence app setup.
2. The base URL for fetching locales is typically: [EXTERNAL_LOCALE_URL]/[YOUR_PROJECT_KEY]/locales/. (Replace [EXTERNAL_LOCALE_URL] with the actual service endpoint provided by Quick Locale Ai and [YOUR_PROJECT_KEY] with your key).
3. Configure your i18n library (e.g., i18next-http-backend) to load translations from this endpoint. The specific URL for a language will be like:

   [EXTERNAL_LOCALE_URL]/[YOUR_PROJECT_KEY]/locales/lng.json

   Where lng is the placeholder for the language code (e.g., "en", "es").

Example with i18next-http-backend:

7. Troubleshooting

• VS Code Extension Not Syncing:
  • Verify the quicklocale.json file is correctly configured with the right Project Key, locale_directory, and locales.
  • Check the VS Code extension's status in the status bar.
  • Ensure you have an active internet connection.
  • Look for any error messages in the VS Code Output panel (select "Quick Locale Ai" from the dropdown).
• Incorrect Text in Application:
  • Ensure the latest changes have been saved in the Confluence localization table.
  • If using the VS Code extension, try a manual resync if the option is available.
  • If using the Live URL, check for caching issues in your application or CDN (if applicable).
  • Confirm the correct localization keys are being used in your UI components.
• AI Translations Not Appearing:
  • Ensure the AI translation feature is enabled for your project in the Confluence app settings.
  • There might be a short delay for AI translations to process, especially for large amounts of text.

8. Frequently Asked Questions (FAQ)

Q: Can I have multiple localization tables in one Confluence space?

A: Typically, each Quick Locale Ai project (and its unique Project Key) corresponds to one primary localization table on a Confluence page. You would configure separate projects for different applications or distinct sets of locales.

Q: What happens if I accidentally edit a locale file in my code?

A: The VS Code extension is designed to make Confluence the source of truth. It will likely overwrite your manual changes with the content from Confluence during the next sync. Some versions might even prevent saving such files directly.

Q: How are conflicts handled if multiple people edit the Confluence table simultaneously?

A: Confluence's native collaborative editing features handle simultaneous edits to the page content itself. Quick Locale Ai processes the saved state of the table.

Q: Is there a limit to the number of locales or keys?

A: Please refer to the specific plan details or service limitations outlined by Quick Locale Ai. For most use cases, the limits are designed to be generous.

9. Support & Contact

If you encounter any issues, have questions, or need assistance with Quick Locale Ai, please reach out to us:

• Support Email: support@quicklocaleai.com
• Documentation: (You are here!) For future reference, this documentation can be found at https://quicklocaleai.com/docs.
• Marketplace Listing: For reviews, updates, and community discussions, visit our page on the Atlassian Marketplace.

We are committed to providing excellent support and continuously improving Quick Locale Ai!