Skip to main content
The HubSpot Connector enables seamless integration between LILT’s translation platform and HubSpot CMS, allowing you to translate HubSpot content (pages, blog posts, marketing emails, forms) directly within your translation workflow. The connector supports both manual content submission and automated scheduled translations.

​
Features

​
Manual Submission

  • Browse and Select Content: Users can browse HubSpot resources by type and select specific content for translation
  • Resource Type Filtering: Filter content by resource type (Site Pages, Landing Pages, Blog Posts, Marketing Emails, Forms)
  • Multi-Select Support: Select multiple resources at once for batch translation
  • Source Language Filtering: Filter resources by source language to only see content in specific languages
  • Instant Materialization: Selected resources are immediately materialized into translation-ready files

​
Automated Schedules

  • Multiple Schedules: Create multiple automated schedules per connector, each with its own configuration
  • Flexible Scheduling: Support for daily and weekly schedules
  • Timezone Support: Configure schedules in any IANA timezone
  • Resource Selection: Choose specific resources or entire resource types for automated translation
  • Change Detection: Only translates content that has changed since the last run (state-aware)
  • Project Naming Templates: Customize project names using templates with placeholders

​
Supported Resource Types

  1. Site Pages (site-pages)
    • Website pages created in HubSpot CMS
    • Translatable: Layout sections, headings, text content, descriptions
  2. Landing Pages (landing-pages)
    • Marketing landing pages
    • Translatable: Layout sections, headings, text content, descriptions
  3. Blog Posts (blog-posts)
    • Blog articles and posts
    • Translatable: Post body, name/title
  4. Marketing Emails (marketing-emails)
    • Email templates and campaigns
    • Translatable: Email subject, content (HTML and plain text), preview text
  5. Forms (Legacy) (forms-legacy)
    • Legacy HubSpot forms (v2 API)
    • Translatable: Field labels, options, submit text, inline messages, validation messages, legal consent text

​
Getting Started

​
Prerequisites

  • A LILT organization account
  • A HubSpot account with CMS access

​
Initial Setup

  1. Navigate to Integrations (Connect): Access the integrations section in your LILT account
  2. Select HubSpot: Choose HubSpot from the available connector options
  3. Initiate OAuth: Click to start the OAuth authentication flow
  4. Authorize Access: Grant LILT the necessary permissions in HubSpot
  5. Complete Setup: The connector will be automatically configured with your HubSpot credentials
💡Alternatively you can initiate this integration directly within the job submission process by selecting Add from Hubspot option under the file selection section.

​
OAuth Authentication Flow

The HubSpot connector uses OAuth 2.0 for secure authentication. The flow works as follows:
  1. Initiation: User clicks “Connect HubSpot” in the LILT interface
  2. Redirect to HubSpot: User is redirected to HubSpot’s OAuth authorization page
  3. Authorization: User grants permissions (scopes: oauth, content, forms)
  4. Token Exchange: HubSpot returns an authorization code
  5. Token Storage: The connector exchanges the code for a refresh token, which is securely stored
  6. Automatic Refresh: Access tokens are automatically refreshed when they expire (typically every 6 hours)
Screenshot 2025 12 08 At 17 40 52

​
OAuth Scopes

The connector requests the following OAuth scopes:
  • oauth: Basic OAuth access
  • content: Access to CMS content (pages, blog posts, etc.)
  • forms: Access to form data

​
Manual Submission

​
Overview

Manual submission allows users to browse HubSpot content and select specific resources for translation on-demand, without setting up automated schedules.

​
Step 1: Access Manual Submission

  1. Navigate to the Create Job or Instant Translate page
  2. Click the Upload button dropdown
  3. Select Add from HubSpot (or similar connector option)
Screenshot 2025 12 11 At 17 39 10

​
Step 2: Browse Resources

  1. The Resource Selection Modal opens
  2. Select a Resource Type from the dropdown:
    • Site Pages
    • Landing Pages
    • Blog Posts
    • Marketing Emails
    • Forms (Legacy)
  3. Resources of the selected type are displayed in a paginated list
  4. Use the Search field to filter resources by name
Screenshot 2025 12 08 At 17 41 11

​
Step 3: Select Content

  1. Single Selection: Click on individual resources to select/deselect them
  2. Bulk Selection: Use “Select All” to select all visible resources
  3. Selected resources are highlighted and tracked
  4. Selection persists when switching between resource types
Screenshot 2025 12 08 At 17 41 28

​
Step 4: Materialize and Submit

  1. Click Add
  2. The connector materializes selected resources:
    • Fetches full content from HubSpot API
    • Filters translatable fields
    • Converts to translation-ready format
  3. Materialized files appear in the job creation interface
  4. Configure translation settings (languages, workflow, etc.)
  5. Submit the job for translation

​
Resource Filtering

  • By Type: Filter to specific resource types (site-pages, landing-pages, blog-posts, etc.)
  • By Source Language: Filter resources by their primary language (e.g., only show English pages)
  • By Search: Search resources by name or identifier

​
Automated Schedules

​
Overview

Automated schedules allow you to set up recurring translation jobs that automatically extract and translate HubSpot content based on a schedule.

​
Schedule Configuration

Each schedule can be configured with:
  • Schedule Type:
    • daily: Runs every day at a specified time
    • weekly: Runs on specific days of the week at a specified time
  • Time of Day: 24-hour format (HH:mm:ss), e.g., “14:30:00” for 2:30 PM
  • Timezone: IANA timezone format (e.g., “America/New_York”, “Europe/London”)
  • Days of Week (for weekly schedules): Array of days: ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
Screenshot 2025 12 11 At 17 50 20

​
Resource Selection for Schedules

Schedules can be configured to translate:
  1. Specific Resources: Provide a list of specific resources with object_id and resource_type
  2. Resource Types: Select entire resource types (e.g., all blog posts, all landing pages)
  3. Combined: Mix of specific resources and resource types

​
Schedule Configuration Fields

  • Source Language: Language code (e.g., “en”, “en-us”) or “auto” for automatic detection
  • Target Languages: Array of target language configurations, each with:
    • target_language: Target language code
    • memory_id: Translation memory ID (optional)
    • model_id: External model ID (optional)
    • instructions: Translation instructions (optional)
  • Workflow ID: LILT workflow to use (e.g., “Translate”, “Translate > Review”)
  • Connector Workflow: instant or verified
  • Project Name Template: Template for project names (supports {{NAME}} placeholder)
  • Options (TBD):
    • include_tags_and_metadata: Include tags and metadata in translation
    • only_send_updated_content: Only send content that has changed

​
Multiple Schedules

The HubSpot connector supports multiple schedules per connector, allowing you to:
  • Create different schedules for different resource types
  • Set different schedules for different languages
  • Configure different workflows for different content types
  • Each schedule runs independently with its own configuration

​
Schedule Limitations

  • One Job Per Day: Each schedule can create at most one job per day
  • Next Run Calculation: The next run time is calculated based on the schedule configuration
  • Timezone Handling: All times are stored and calculated in UTC

​
Technical Limitations

  1. One Connector Per HubSpot Site: Each LILT organization can connect to only one HubSpot account/site. Attempting to create a second HubSpot connector for the same organization will result in an error: “A connectors configuration already exists for this organization and kind”
  2. OAuth Scope: The connector requires specific OAuth scopes (oauth, content, forms). If these scopes are not granted, the connector will not function properly.
  3. API Rate Limits: HubSpot API has rate limits. The connector implements retry logic with exponential backoff, but very high-volume operations may be throttled.
  4. Content Format: The connector works with HubSpot’s CMS API structure. Custom modules or non-standard content structures may not be fully supported.
  5. Language Variations: HubSpot manages language variations separately. The connector delivers translations as new language variations in HubSpot.
  6. Form API Version: Currently, only legacy forms (v2 API) are fully supported. The new forms API (v3) is not yet fully available in HubSpot.
  7. Forms and Marketing Emails delivery: Delivery for this content types are returned as cloned versions of the original selected resource. This is because this CRM content does not support language variations.

​
Error Troubleshooting

This section provides detailed information about common errors, their explanations, and step-by-step solutions.

​
OAuth and Authentication Errors

Error: “OAuth code not found” or “OAuth authorization failed” Explanation: This error occurs when the OAuth flow is interrupted or the authorization code is missing from the callback. This can happen if:
  • The user cancels the authorization in HubSpot
  • The redirect URI is misconfigured
  • The OAuth state parameter is invalid or expired
  • Network issues during the OAuth callback
How to Solve:
  1. Retry the OAuth flow: Navigate back to Integrations → HubSpot and click “Connect” again
  2. Check redirect URI: Ensure the redirect URI in HubSpot app settings matches: {connectors_webhooks_url}/webhooks/oauth/hubspot/redirect
  3. Clear browser cache: Clear cookies and cache, then retry
  4. Check HubSpot app status: Verify your HubSpot app is active and has the correct scopes configured
  5. Verify network connectivity: Ensure there are no firewall or network issues blocking the OAuth callback
Error: “A connectors configuration already exists for this organization and kind” Explanation: Only one HubSpot connector can exist per LILT organization. This error occurs when attempting to create a second HubSpot connector for the same organization. How to Solve:
  1. Use existing connector: If you need to connect to the same HubSpot site, use the existing connector configuration
  2. Update existing connector: If you need to change HubSpot accounts, disconnect the current connector first, then create a new one
  3. Use separate organization: If you need to connect to a different HubSpot site, create a separate LILT organization for that connection
  4. Delete old connector: If the existing connector is no longer needed, delete it first before creating a new one

​
Resource and Content Errors

Error: “Unable to determine HubSpot resource type from filename” Explanation: The connector couldn’t parse the resource type and ID from the translated file’s filename. This typically happens when:
  • The filename format is incorrect (should be {resource_type}_{object_id}.json+html)
  • The file was manually modified or corrupted
  • The resource type is not supported
How to Solve:
  1. Check file format: Ensure files follow the naming convention: {resource_type}_{object_id}.json+html (e.g., landing-pages_12345.json+html)
  2. Verify resource type: Ensure the resource type is one of the supported types (site-pages, landing-pages, blog-posts, marketing-emails, forms-legacy)
  3. Re-materialize resources: If using manual submission, re-select and materialize the resources
  4. Check connector logs: Review logs for the specific resource that failed to identify the issue
Error: “No resources to extract” or “No resources found” Explanation: The connector couldn’t find any resources matching the specified criteria. This can occur when:
  • The source language filter doesn’t match any resources
  • The resource type has no content
  • The OAuth token doesn’t have access to the resources
  • The HubSpot account has no content of the selected type
How to Solve:
  1. Check source language filter: Verify the source language matches your content’s primary language (e.g., “en” for English, “en-us” for US English)
  2. Remove language filter: Try removing the source language filter to see all resources
  3. Verify resource type: Ensure the selected resource type exists in your HubSpot account
  4. Check HubSpot permissions: Verify the OAuth token has access to the CMS content (check scopes)
  5. Test with different resource type: Try selecting a different resource type to confirm the connector is working
Error: “Failed to materialize HubSpot resource” or “Resource not found” Explanation: The connector couldn’t retrieve the full content of a specific resource from HubSpot. This can happen when:
  • The resource was deleted in HubSpot after selection
  • The resource ID is invalid
  • The OAuth token doesn’t have permission to access the specific resource
  • The HubSpot API is temporarily unavailable
How to Solve:
  1. Verify resource exists: Check in HubSpot that the resource still exists and hasn’t been deleted
  2. Re-select resources: In manual submission, re-select the resources and try again
  3. Check permissions: Ensure the OAuth token has the content scope and access to the specific resource
  4. Retry operation: Wait a few minutes and retry, as this could be a temporary API issue
  5. Check HubSpot API status: Verify HubSpot’s API status page for any known issues

​
Translation Delivery Errors

Error: “Failed to deliver translated content to HubSpot” or “BadRequestProblem” Explanation: The connector couldn’t deliver translated content back to HubSpot. This can occur due to:
  • Invalid JSON format in translated content
  • Missing required fields in the translated content
  • HubSpot API validation errors
  • Network connectivity issues
  • API rate limiting
How to Solve:
  1. Check translation job status: Verify the translation job completed successfully in LILT
  2. Validate JSON format: Ensure the translated content is valid JSON (check for syntax errors)
  3. Review HubSpot API response: Check connector logs for the specific HubSpot API error message
  4. Retry delivery: Some errors are transient; try re-delivering the translation
  5. Check API rate limits: If you’re processing many resources, you may be hitting HubSpot’s rate limits - wait and retry
  6. Verify resource still exists: Ensure the target resource hasn’t been deleted in HubSpot
Error: “LANGUAGE_ALREADY_TRANSLATED” (treated as success) Explanation: This is not actually an error - it’s an informational message. HubSpot returns this when attempting to create a language variation that already exists. The connector treats this as a success case and skips creating a duplicate. How to Solve:
  • No action needed: This is expected behavior. The translation already exists in HubSpot for that language
  • Update existing translation: If you want to update the existing translation, delete the language variation in HubSpot first, then re-deliver

​
Schedule and Automation Errors

Error: “Schedule not running” or “No jobs created for schedule” Explanation: A scheduled translation job didn’t execute as expected. This can happen when:
  • The schedule configuration is invalid
  • The next run time hasn’t been reached
  • The schedule already ran today (one job per day limit)
  • The scheduler service is not running
  • There are no resources matching the schedule criteria
How to Solve:
  1. Check schedule configuration: Verify the schedule type, time, timezone, and resource selection are correct
  2. Verify next run time: Check the schedule’s next_run timestamp to ensure it’s in the past
  3. Check one-per-day limit: Each schedule can only create one job per day. If it already ran today, wait until tomorrow
  4. Verify resources exist: Ensure there are resources matching the schedule’s resource type and source language criteria
  5. Check scheduler service: Verify the connector scheduler service is running (contact support if needed)
  6. Review schedule logs: Check connector logs for any errors during schedule execution
Error: “source_language is required in scheduler_settings” Explanation: A scheduled job was created without a source language specified in the schedule configuration. The source language is required for the connector to filter and process resources correctly. How to Solve:
  1. Update schedule configuration: Edit the schedule and ensure a source_language is specified (e.g., “en”, “en-us”, or “auto” for automatic detection)
  2. Verify schedule settings: Check that the schedule configuration includes all required fields:
    • source_language
    • target_languages
    • schedule (with kind, time_of_day, timezone)
    • resource_types or resources
  3. Recreate schedule: If the configuration is corrupted, delete and recreate the schedule with proper settings
Error: “No target languages configured” or “target_languages is empty” Explanation: The schedule configuration doesn’t have any target languages specified, so the connector doesn’t know which languages to translate to. How to Solve:
  1. Add target languages: Edit the schedule and add at least one target language configuration
  2. Verify target language format: Ensure each target language has:
    • target_language: Language code (e.g., “fr”, “es”, “de”)
    • Optional: memory_id, model_id, instructions
  3. Check schedule validation: Use the connector validation feature to verify the schedule configuration is correct

​
API and Network Errors

Error: “RequestException” or “Network error” Explanation: The connector couldn’t communicate with HubSpot’s API. This can be due to:
  • Network connectivity issues
  • HubSpot API being temporarily unavailable
  • Firewall or proxy blocking requests
  • DNS resolution problems
How to Solve:
  1. Check network connectivity: Verify the system can reach api.hubapi.com
  2. Check HubSpot status: Visit HubSpot’s status page to see if there are known API issues
  3. Retry operation: Network errors are often transient - wait a few minutes and retry
  4. Check firewall rules: Ensure outbound HTTPS connections to api.hubapi.com are allowed
  5. Review DNS settings: Verify DNS can resolve HubSpot’s API domain
  6. Check proxy settings: If using a proxy, ensure it’s correctly configured
Error: “Rate limit exceeded” or “429 Too Many Requests” Explanation: HubSpot’s API has rate limits, and the connector has exceeded the allowed number of requests in a given time period. HubSpot typically allows a certain number of requests per minute/hour. How to Solve:
  1. Wait and retry: Rate limits reset after a time period. Wait 1-5 minutes and retry
  2. Reduce batch size: If processing many resources, reduce the number of resources processed at once
  3. Space out operations: For scheduled jobs, consider spreading them across different times
  4. Check HubSpot plan limits: Verify your HubSpot plan’s API rate limits
  5. Use retry logic: The connector automatically retries with exponential backoff, but you may need to wait longer