Localization

Configure regional settings including measurement units, rulers, guides, and grid for the PDF Web SDK. The ui.IUnitsAndGuidesConfig interface provides comprehensive localization options.

unitsAndGuides

Configure measurement units and visual guides for the document canvas.

Measurement Units

Set the default measurement unit for the viewer:

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.millimeters,
  },
});
Copy

Available units:

enum Units {
  unit, // Generic unit
  inch, // Inches
  millimeters, // Millimeters
  centimeters, // Centimeters
  point, // Points (default, 72 points = 1 inch)
}
Copy

Unit Examples

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

// Metric system (millimeters)
const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.millimeters,
  },
});

// Imperial system (inches)
const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.inch,
  },
});

// Desktop publishing (points)
const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.point,
  },
});
Copy

Rulers Configuration

Control ruler visibility when opening documents:

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.millimeters,
    showRulersWhenOpeningDocuments: true, // Show rulers by default
  },
});
Copy

Default: false (rulers hidden)

Guides Configuration

Set the color for alignment guides:

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.centimeters,
    showRulersWhenOpeningDocuments: true,
    guidesColor: '#0000FF', // Blue alignment guides
  },
});
Copy

Default: '#0000FF' (blue)

Grid Configuration

Configure the document grid using the ui.IGridConfig interface:

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.point,
    grid: {
      lineColor: '#CCCCCC', // Grid line color
      subdivisions: 3, // Number of subdivisions
      offsetTop: 0, // Top offset, in `units`
      offsetLeft: 0, // Left offset, in `units`
      width: 72, // Grid width (72 points = 1 inch)
      height: 72, // Grid height (72 points = 1 inch)
    },
  },
});
Copy

Grid Properties

• lineColor: Hex color string for grid lines

  • Default: '#000000' (black)

• subdivisions: Number of grid subdivisions

  • Default: 3

• offsetTop: Vertical offset, in the configured units

  • Default: 0

• offsetLeft: Horizontal offset, in the configured units

  • Default: 0

• width: Grid cell width, in the configured units

  • Default: 72 (1 inch with the default Units.point)

• height: Grid cell height, in the configured units

  • Default: 72 (1 inch with the default Units.point)

Dynamic Updates with setUnitsAndGuides()

Update units and guides configuration at runtime:

const viewer = editor.ui.pdfWebElement;

// Change to metric units
viewer.setUnitsAndGuides({
  units: Units.millimeters,
  showRulersWhenOpeningDocuments: true,
});

// Update grid settings
viewer.setUnitsAndGuides({
  units: Units.centimeters,
  grid: {
    lineColor: '#FF0000',
    width: 50,
    height: 50,
  },
});
Copy

Complete Regional Examples

European Setup (Metric)

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  unitsAndGuides: {
    units: Units.millimeters,
    showRulersWhenOpeningDocuments: true,
    guidesColor: '#0000FF',
    grid: {
      lineColor: '#CCCCCC',
      subdivisions: 4,
      width: 10, // 10mm grid
      height: 10,
    },
  },
});
Copy

US Setup (Imperial)

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  unitsAndGuides: {
    units: Units.inch,
    showRulersWhenOpeningDocuments: true,
    guidesColor: '#00FF00',
    grid: {
      lineColor: '#DDDDDD',
      subdivisions: 8,
      width: 1, // 1 inch (grid values use `units`)
      height: 1,
    },
  },
});
Copy

Asian Setup (Points)

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  unitsAndGuides: {
    units: Units.point,
    showRulersWhenOpeningDocuments: false,
  },
});
Copy

Design/Print Setup

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  unitsAndGuides: {
    units: Units.point,
    showRulersWhenOpeningDocuments: true,
    guidesColor: '#FF00FF',
    grid: {
      lineColor: '#E0E0E0',
      subdivisions: 6,
      width: 36, // Half inch (36 points)
      height: 36,
    },
  },
});
Copy

Runtime Region Switching

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),
  unitsAndGuides: {
    units: Units.inch,
  },
});

const viewer = editor.ui.pdfWebElement;

// User switches to European region
function switchToMetric() {
  viewer.setUnitsAndGuides({
    units: Units.centimeters,
    showRulersWhenOpeningDocuments: true,
    grid: {
      lineColor: '#CCCCCC',
      width: 1, // 1 cm (grid values use `units`)
      height: 1,
    },
  });
}

// User switches to US region
function switchToImperial() {
  viewer.setUnitsAndGuides({
    units: Units.inch,
    showRulersWhenOpeningDocuments: true,
    grid: {
      lineColor: '#DDDDDD',
      width: 1, // 1 inch
      height: 1,
    },
  });
}
Copy

Combined Language & Localization

Combine with language settings for complete regional configuration:

import { PdfEditor, Units } from '@avanquest/pdf-web-viewer';

const editor = await PdfEditor({
  license: 'YOUR_LICENSE_KEY',
  container: document.getElementById('pdf-container'),

  // German language
  languageConfig: {
    code: 'de',
  },

  // Metric units
  unitsAndGuides: {
    units: Units.centimeters,
    showRulersWhenOpeningDocuments: true,
    guidesColor: '#0000FF',
    grid: {
      lineColor: '#CCCCCC',
      subdivisions: 5,
      width: 10,
      height: 10,
    },
  },
});

const viewer = editor.ui.pdfWebElement;

// Switch to French region
viewer.setLanguage({ code: 'fr' });
viewer.setUnitsAndGuides({ units: Units.millimeters });

// Switch to Japanese region
viewer.setLanguage({ code: 'ja' });
viewer.setUnitsAndGuides({ units: Units.point });
Copy

Reference

• ui.IUnitsAndGuidesConfig - Units and guides interface
• ui.IGridConfig - Grid configuration interface
• ui.IDocumentViewerWrapperElement.setUnitsAndGuides - Dynamic units updates
• ui.Units - Available measurement units enum
• Language Configuration - UI language settings