File Upload and Import
Learn how to upload and import translation files into MovaBase
File Upload and Import
MovaBase makes it easy to import your existing translation files, whether you're migrating from another platform or just getting started. This guide covers everything you need to know about uploading translation files in various formats.
Supported File Formats
MovaBase supports multiple file formats to accommodate different platforms and workflows:
| Format | Extension | Platform | Use Case |
|---|---|---|---|
| JSON | .json | Web applications | JavaScript frameworks, React, Vue, Next.js |
| PO | .po | Linux/Desktop | Gettext format, internationalization libraries |
| Android XML | .xml | Android apps | Android resource files |
| iOS Strings | .strings | iOS apps | iOS/macOS resource files |
All formats are automatically detected based on the file extension. MovaBase parses and normalizes the content into a consistent internal format for easy management.
Upload Overview
NEEDS_MEDIA
The file upload feature allows you to:
- Import Existing Translations: Bring your current translations into MovaBase quickly
- Update Existing Files: Upload new versions of translation files to update content
- Add New Languages: Upload translation files for languages you haven't added yet
- Merge Content: Combine uploaded translations with existing ones without losing data
When to Use File Upload
Use file upload when:
- Setting up a new project with existing translations
- Updating translations from external tools or services
- Importing translations from multiple platforms
- Adding new languages to an existing project
- Syncing manual translation work back into MovaBase
Uploading Translation Files
Open Upload Dialog
Access the upload feature from your project dashboard:
- Navigate to your project
- Click the Upload button (folder icon with upload symbol)
- The upload dialog will open
The upload button is available in the project toolbar, making it easily accessible from any view within your project.
Select File
Choose the translation file you want to upload:
- Click Choose a file to open the file picker
- Select a file with one of the supported formats (JSON, PO, XML, or .strings)
- The file name will be displayed once selected
Ensure your file uses one of the supported extensions. Unsupported file types will be rejected with an error message.
Select Language
Specify which language the uploaded file contains:
- Choose a language from the dropdown menu
- All languages configured in your project will appear
- The language must already exist in your project
If you need to add a new language, do so from the Language Management section before uploading the file.
Upload and Process
Complete the upload process:
- Review your selections (file and language)
- Click Upload to begin processing
- Wait for the file to be parsed and imported
- A success message will appear when complete
MovaBase automatically parses the file, creates or updates the necessary file structure, and imports all translation keys and values.
NEEDS_MEDIA
File Structure Handling
How MovaBase organizes your uploaded translations depends on your project's download mode.
File-Based Mode
In file-based mode, MovaBase preserves the file structure and names from your uploads:
Project/
├── en/
│ ├── common.json ← Uploaded: common.json for English
│ ├── auth.json ← Uploaded: auth.json for English
│ └── dashboard.json ← Uploaded: dashboard.json for English
├── es/
│ ├── common.json ← Uploaded: common.json for Spanish
│ ├── auth.json ← Uploaded: auth.json for Spanish
│ └── dashboard.json ← Uploaded: dashboard.json for SpanishWhen uploading in file-based mode, the file name from your upload is preserved and used to organize translations. This matches how you likely structure files in your application.
Language-Based Mode
In language-based mode, all translations are consolidated into a single file per language:
Project/
├── en.json ← All English translations from various uploads merged
├── es.json ← All Spanish translations from various uploads merged
└── fr.json ← All French translations from various uploads mergedIn language-based mode, uploaded files are merged into the appropriate language file. Translation keys from different files are combined into a single structure.
Linked Project Handling
If your project is linked to another project, MovaBase intelligently manages translation distribution between the two projects.
How Linked Projects Work
Linked projects allow you to share common translations across multiple projects while maintaining project-specific content. When you upload a file:
| Scenario | Behavior |
|---|---|
| Key exists in linked project | Translation is updated in the linked project |
| Key doesn't exist in linked project | Translation is added to the current project |
| No linked project | All translations are added to the current project |
This intelligent distribution ensures that shared translations remain consistent across all linked projects while allowing project-specific translations to stay separate.
Upload Process with Linked Projects
Bulk Import and Performance
MovaBase uses bulk upsert operations to handle large translation files efficiently.
Performance Features
- Bulk Upserts: Multiple translations are inserted/updated in a single operation
- Optimized Parsing: Files are parsed quickly using optimized format handlers
- Efficient Storage: Translations are stored in a normalized database structure
- Fast Lookups: Translation keys are indexed for quick retrieval
The bulk upload system is designed to handle files with thousands of translation keys without performance issues. Large files are processed efficiently in the background.
Upload Limits and Considerations
| Factor | Limitation |
|---|---|
| File Size | Up to 10MB per file |
| Translation Keys | Unlimited (bulk optimized) |
| Concurrent Uploads | One at a time per project |
| Formats | JSON, PO, Android XML, iOS Strings |
Error Handling and Validation
MovaBase provides clear feedback when issues occur during upload.
Common Upload Errors
Validation Rules
Before processing uploads, MovaBase validates:
- Extension Check: File must have a supported extension
- Size Limit: File must be under 10MB
- Readable Content: File must be text-based and readable
- Non-Empty: File must contain translation data
- Valid Syntax: Content must match the format specification
- Key Structure: Translation keys must be strings
- Value Types: Values must be strings or valid nested structures
- Encoding: UTF-8 encoding is required
- Language Exists: Selected language must be in project
- Code Matching: Language code must match project configuration
- Active Language: Language must be enabled in project
Best Practices
Follow these best practices for smooth file uploads:
File Preparation
- Validate Files Before Upload: Use format-specific validators to ensure your files are valid
- Use Consistent Naming: Maintain consistent file names across languages (e.g.,
common.json,auth.json) - Organize by Feature: Group related translations in the same file for better organization
- Use UTF-8 Encoding: Ensure all files are saved with UTF-8 encoding
Upload Strategy
- Upload Default Language First: Start with your primary/source language
- Verify Before Bulk Upload: Test with a small file before uploading large files
- Use Linked Projects: Leverage linked projects for shared translations
- Maintain Backup: Keep backups of your original files before major updates
Consider setting up a workflow where you upload files to a staging project first, verify the content, then move to production once you're satisfied with the results.
Common Workflows
Troubleshooting
If you encounter persistent upload issues, check the browser console for detailed error messages. This can help identify specific problems with file format or content.
Issues and Solutions
| Issue | Possible Cause | Solution |
|---|---|---|
| File not accepted | Wrong extension | Rename file with correct extension |
| Upload fails | Invalid file content | Validate file format using external validator |
| Translations missing | Language not selected | Ensure language is properly selected in dialog |
| Duplicates appear | Uploading same file multiple times | MovaBase handles this by updating existing keys |
| Partial upload | Network interruption | Check internet connection and try again |
Next Steps
Now that you understand how to upload and import translation files, you can:
- Explore File Management: Learn how to organize and manage your translation files
- Search and Filter: Use advanced search to find specific translations
- Set Up Integrations: Configure Bitbucket integration for automatic syncing
- Use Download Features: Export translations in your preferred format
Part 8 of 14 • File Upload and Import Complete
Next: File Management