Skip to main content
  • Send to AI

Text Translation - Enablement & Configuration

Introduction​

This guide provides store administrators and technical teams with information about enabling and managing the Text Translation feature on the Publica.la platform. It covers configuration options, prerequisites, and best practices for deploying translation capabilities to your readers.

Feature Availability​

Prerequisites for Enablement​

Text Translation is available for tenants meeting these requirements:

  1. Active Plan: Subscription plan that includes AI features
  2. Publication Compatibility: Publications must be in supported formats (PDF, EPUB, Audiobook)
  3. Reading Session Active: Translation is only available within active reading sessions
  4. Network Connectivity: Users require active internet connection for translations

Default Configuration​

  • Status: Translation is enabled by default for eligible tenants
  • Opt-In User Experience: While enabled on the platform, individual users must actively use the feature
  • No User Restrictions: All readers can access translation functionality (no per-user configuration required)

Technical Configuration​

Backend Configuration​

Translation functionality is managed through the following environment variables and configuration files:

API Endpoint:

  • Endpoint: /integrations/google-translate (legacy naming for backward compatibility)
  • Method: POST
  • Authentication: Session-based (within active reader session)

Configuration Files:

  • config/google-translate.php - Supported languages list
  • config/ai.services - AI provider configuration (OpenAI)

Environment Variables:

  • GOOGLE_CLOUD_TRANSLATION_API - OpenAI API key for translation service (despite legacy naming)

Supported Languages Configuration​

The supported languages list is maintained in config/google-translate.php and includes 112 languages:

To add or modify supported languages:

  1. Contact the engineering team
  2. Update config/google-translate.php with new language codes
  3. Deploy configuration changes
  4. Verify through the Reader interface

Monitoring & Analytics​

Tracking Translation Activity​

Translation requests are tracked for analytics purposes:

  • Activity Logging: Each translation is logged with user, session, and publication context
  • Error Tracking: Failed translations are recorded for troubleshooting
  • Performance Metrics: Translation response times are monitored
  • Tenant Analytics: Translation usage is tracked per tenant for billing and analytics

Accessing Translation Metrics​

Store administrators can view translation usage through:

  1. Admin Dashboard: Translation metrics in engagement analytics
  2. Reporting Tools: Custom reports on AI feature usage
  3. Support Portal: Usage statistics and trend analysis

Security & Compliance​

Content Security​

The translation feature implements multi-layered security:

Data Encryption:

  • All translation requests and responses are encrypted in transit
  • Content encryption at rest follows platform standards
  • Encryption keys are tenant-specific and isolated

Session Security:

  • Translations are scoped to the current user session
  • Data is not persisted beyond the session
  • Session isolation prevents cross-tenant data leakage

Content Protection:

  • Selected text is the only content transmitted to AI services
  • Full publication content is never exposed to external services
  • Multi-tenant architecture ensures complete isolation

Privacy Compliance​

Translation respects platform privacy standards:

  • GDPR Compliance: User data handling follows GDPR requirements
  • Data Retention: No permanent storage of translated content
  • User Consent: Built into the reading experience (opt-in feature)
  • Third-Party Agreements: OpenAI contract includes data protection clauses

Troubleshooting Guide​

Common Issues​

Translation Requests Failing​

Symptoms: Users see error messages when attempting translations

Causes:

  • Network connectivity issues
  • AI service unavailability
  • Invalid API configuration
  • Session timeout

Resolution:

  1. Check user network connection
  2. Verify OpenAI API status
  3. Confirm API key validity in configuration
  4. Check reading session is active
  5. Contact support if issue persists

Slow Translation Response​

Symptoms: Translations take longer than expected (>10 seconds)

Causes:

  • Network latency
  • AI service processing delay
  • Large text selection
  • System load

Resolution:

  1. Check network connectivity
  2. Retry the translation
  3. Try selecting smaller text portions
  4. Check system performance metrics
  5. Contact support for persistent issues

Inaccurate Translations​

Symptoms: Translations are semantically incorrect or poorly formatted

Causes:

  • Complex language or terminology
  • Context-dependent content
  • Ambiguous source text
  • AI model limitations

Resolution:

  1. Verify source language is correctly detected
  2. Try with complete phrases vs. isolated words
  3. Check target language selection
  4. Provide feedback through support for model improvement

Language Not Appearing in List​

Symptoms: Expected language is missing from language selection dropdown

Causes:

  • Language not in supported list
  • Configuration issue
  • Browser cache issue

Resolution:

  1. Verify language is in supported list
  2. Clear browser cache
  3. Refresh the Reader interface
  4. Check configuration files
  5. Contact support if language should be available

Best Practices for Store Administrators​

Communicating the Feature to Users​

  1. Include in Release Notes: Notify users of translation availability in new releases
  2. Documentation Links: Provide links to user-facing feature documentation
  3. In-App Guidance: Implement tooltips or help text in the Reader interface
  4. Training Materials: Create user guides for non-technical audiences

Monitoring Usage​

  1. Regular Reviews: Monitor translation metrics quarterly
  2. Performance Tracking: Watch for degradation in translation response times
  3. Error Analysis: Review translation failures to identify patterns
  4. User Feedback: Collect feedback from users on translation quality

Optimizing for Your Audience​

  1. Language Focus: Ensure frequently needed languages are in your supported list
  2. Feature Communication: Highlight translation in store marketing materials
  3. Integration: Consider how translation fits with other AI features (definitions, explanations)
  4. Accessibility: Ensure translation feature is discoverable in your Reader UI

Performance Optimization​

Response Time Targets​

  • Target Response Time: < 3 seconds for most translation requests
  • Maximum Timeout: 10 seconds per request
  • Retry Logic: Failed requests are handled gracefully

Optimization Strategies​

  1. Caching: Platform caches common translation patterns
  2. Model Selection: Uses efficient GPT-4.1-nano model
  3. Session Optimization: Translations are optimized for active reading sessions
  4. Load Balancing: AI requests are distributed across available capacity

Support Resources​

For Store Administrators​

  • Support Portal: Access knowledge base articles on translation configuration
  • Admin Dashboard: Monitor translation metrics and user engagement
  • Technical Support: Email support@publica.la for configuration issues

For End Users​

  • Help Documentation: In-app help links direct to feature documentation
  • Reader Support: Translation errors include actionable error messages
  • Feedback Mechanism: Users can report translation quality issues through app

Future Roadmap​

Planned improvements to the Text Translation feature:

  • Performance: Faster response times through model optimization
  • Languages: Additional language support based on user requests
  • Features: Integration with other AI features (definitions, explanations)
  • Analytics: Enhanced usage analytics and reporting
  • Customization: Tenant-specific language preferences and branding
X

Graph View