Back to Import Center

How to Import Dictionaries from R2/S3 Buckets

A step-by-step guide to setting up cloud storage and importing your dictionaries from R2 or S3-compatible buckets.

What you'll need:

  • A Cloudflare R2 account (recommended) or any S3-compatible storage provider
  • MDict dictionary files (.mdx and optional .mdd files) uploaded to your bucket
  • API credentials (Access Key ID and Secret Access Key)

Step 1: Setting Up Cloudflare R2

1.1 Create an R2 Bucket

  1. Log in to your Cloudflare dashboard
  2. Navigate to R2 from the left sidebar
  3. Click Create bucket
  4. Enter a name for your bucket (e.g., my-dictionaries)
  5. Select your preferred location (choose one close to you for better performance)
  6. Click Create bucket

1.2 Upload Dictionary Files

  1. Open your newly created bucket
  2. Click Upload
  3. Upload your dictionary files (.mdx files and their associated .mdd resource files)
  4. Make sure related files share the same base name (e.g., Oxford.mdx, Oxford.mdd)

1.3 Enable Public Access (Required)

  1. In your bucket settings, find the Public Access section
  2. Click Connect Domain or Allow Access
  3. You can either:
    • Use R2's default public URL (e.g., https://pub-xxxxx.r2.dev)
    • Connect a custom domain you own for cleaner URLs
  4. Copy the Public Bucket URL - you'll need this later

1.4 Generate API Tokens

  1. Go back to the R2 overview page
  2. Click Manage R2 API Tokens
  3. Click Create API Token
  4. Configure the token:
    • Token name: e.g., "WordHub Dictionary Access"
    • Permissions: Select Object Read (read-only is sufficient)
    • TTL: Choose "Forever" or set an expiration date
    • (Optional) Restrict to specific buckets for better security
  5. Click Create API Token
  6. Important: Copy and save these credentials immediately (they won't be shown again):
    • Access Key ID
    • Secret Access Key
    • Endpoint URL (usually https://<account-id>.r2.cloudflarestorage.com)

Step 2: Using Other S3-Compatible Providers

WordHub also supports other S3-compatible storage services like AWS S3, MinIO, Backblaze B2, DigitalOcean Spaces, and more. The setup process is similar:

Create a bucket in your provider's console

Upload your dictionary files to the bucket

Enable public read access or configure appropriate permissions

Generate access credentials (Access Key ID and Secret Access Key)

Note down your bucket's public URL and endpoint URL

Step 3: Importing Dictionaries in WordHub

3.1 Start the Import Process

  1. Go to the Dictionary Import Center
  2. Click Start Dictionary Import
  3. Select Bucket URL (not Local Files)

3.2 Enter Your Credentials

  1. Bucket URL: Paste your bucket's public URL (e.g., https://pub-xxxxx.r2.dev)
  2. Access Key ID: Paste the Access Key ID from Step 1.4
  3. Secret Access Key: Paste the Secret Access Key from Step 1.4
  4. Region: For Cloudflare R2, select Auto. For other providers, select the appropriate region.
  5. Endpoint (Optional): If using a custom endpoint, enter it here (e.g., for Cloudflare R2: https://<account-id>.r2.cloudflarestorage.com)

3.3 Test and Discover

  1. Click Test Connection to verify your credentials
  2. If the connection is successful, click Discover Files
  3. WordHub will scan your bucket and group dictionary files automatically
  4. Review the discovered dictionaries and select which ones to import
  5. Click Import Selected Dictionaries to begin the import

Troubleshooting

"Connection Failed" or "Access Denied"

  • Verify your Access Key ID and Secret Access Key are correct
  • Check that your bucket has public read access enabled
  • Ensure the API token has the correct permissions (at least Object Read)
  • Make sure the bucket URL is the public URL, not the API endpoint

"No Dictionary Files Found"

  • Confirm that .mdx files are present in your bucket
  • Check that files are at the root level or in the bucket directly (not in deeply nested folders)
  • Verify file names follow the correct naming convention (e.g., Dictionary.mdx, Dictionary.mdd)

"Region/Endpoint Issues"

  • For Cloudflare R2, use "Auto" region and optionally specify the endpoint
  • For AWS S3, select the correct region where your bucket is located
  • For other providers, consult their documentation for the correct endpoint URL and region settings

Security Best Practices

Use read-only permissions: Grant only Object Read access to your API tokens to prevent unauthorized modifications.

Restrict token scope: Limit API tokens to specific buckets rather than giving account-wide access.

Set token expiration: Consider setting an expiration date for your API tokens and rotate them regularly.

Keep credentials private: Never share your Access Key ID and Secret Access Key publicly.

Ready to import your dictionaries?

Go to Import Center