HubSpot

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. This can be done through language selection in the LILT job submission page.
• 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

Language variants — For site pages, landing pages, and blog posts, the connector automatically creates a language variant in HubSpot for each target language. If a variant already exists, it is updated. You do not need to manually create language variants for each page — the connector handles this automatically. Copies — For marketing emails and forms, HubSpot does not support language variants. Instead, the connector looks for an existing copy with the same name followed by a dash and the target language code (e.g., some-name - en-US). If a match is found, it updates that content. Otherwise, it creates a new copy using that naming format.

​

Prerequisites

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

Note: Free HubSpot accounts are limited to 3 language variants per page. If you need more target languages, confirm your HubSpot plan supports the number of language variants you require.

​

Initial Setup

​

Step 1: Connect HubSpot to LILT

1. Tell your LILT team you would like to add a HubSpot integration so they can enable HubSpot connectivity.
2. Navigate to the Job Submission Page in LILT
3. Select the HubSpot icon
   
4. Click Sign in to your HubSpot account to start the OAuth authentication flow
5. You will be redirected to HubSpot — authorize LILT to access your content
6. Once authorized, you are redirected back to LILT and the connector is ready to use

​

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
   

​

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.

​

Browsing and selecting content

1. Navigate to Create Job or Instant Translate
2. Select the Source Language in LILT first, to show only content in that specific language
3. Click the Upload dropdown and select Add from HubSpot
   
4. In the resource selection modal, choose a Resource Type from the dropdown:
   • Site Pages
   • Landing Pages
   • Blog Posts
   • Marketing Emails
   • Forms (Legacy)
5. Use the Search field to find specific resources by name
6. Click Add — the connector fetches full content from HubSpot and prepares it for translation
7. Configure translation settings (workflow, etc.)
8. Click Submit to start the translation

Pagination: For resource types with many items, navigate through paginated results. Your selections persist across pages.

​

Tracking translation status

After submission, jobs progress through the following stages: Draft > Submitted > In-progress > Complete. Instant translations are processed automatically. No further action is needed — the translated content is delivered back to HubSpot once the job reaches “Complete.” Verified translations are sent to the LILT platform for human review. Once the linguist completes their review, the translated content is delivered back and the job status updates to “Complete.”

​

What happens after delivery

• Site Pages, Landing Pages, and Blog Posts: A new language variant is created (or updated) in HubSpot. The source content is never modified.
• Marketing Emails and Forms: A new copy is created with the target language code appended to the name (e.g., Newsletter - es). If a copy already exists for that language, it is updated.

​

Re-translating content

• Submitting the same resource for the same target language again will update the existing translation — no duplicates are created.

​

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"]

​

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. Reload resources: If using manual submission, re-select and reload 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