eduKate Singapore

VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Next useful routeCanonical hubHELP

How People Translate Quickly | OGC KML 2.3 Placemark BalloonStyle Translation QA: Preserve Map Data and Substitution Keys

—

by

eduKate Asia

To translate a KML Placemark balloon quickly, change the human-readable labels, explanations and approved template sentences while preserving the spatial feature, its coordinate values, its style references and the substitution tokens that insert feature-specific data. In a shared KML BalloonStyle, text such as a visitor-facing instruction can be translated, but a token such as $[name] or $[surveyStatus] is an instruction to a KML viewer, not ordinary English. A misplaced character can turn dynamic map information into a literal, broken label.

A reliable KML 2.3 localization workflow first inventories the Placemarks, their <name> and <description> values, the shared styles, and their ExtendedData fields. It then translates only the permitted text, checks that the KML remains well-formed, resolves every style reference and substitution name, and opens the result in a compatible viewer. The coordinates, region rules, network link targets and feature identities should be the same before and after a language-only release unless a separate map-editing task has been approved.

The specific reader job is not “translate a map” in the abstract. It is to make one KML popup or a family of shared popup templates understandable to readers of another language without changing which geographic object they are inspecting or the data being reported. This guide focuses on the BalloonStyle text template, Data/displayName distinctions, HTML inside descriptive fields, repeatable validation and repair. OGC KML 2.3 and Google Earth’s KML ExtendedData documentation provide the relevant technical starting points; individual viewers may support different rendering behaviors.

What the popup is actually made of

A Placemark represents a geographic feature or annotation that can have a name, description, style and geometry. Its balloon is a user-facing presentation of information about that feature. A simple file might have a separate description for each Placemark, but a larger project often defines a shared style that every Placemark references. That style can contain a BalloonStyle text template. The viewer combines the shared template with the values of the currently selected feature, so the same template can show different place names and measurements.

This separation changes the translation workflow. A translator looking at one screenshot may think all visible words belong to that feature. In reality, part of the sentence may live in a shared style, part in the Placemark’s name, and part in ExtendedData. The first question is therefore where each visible word originates. Without that source map, the team may change one Placemark’s description but leave the repeated template untranslated, or translate the shared template and accidentally change every popup without testing the other feature types.

There are also important differences between a KML data field’s machine name and its display label. An ExtendedData element can contain a Data record whose name attribute is used to refer to that record. Its displayName child is meant for a human-readable label, while its value child contains the associated data. If the shared BalloonStyle refers to $[surveyStatus], changing Data name="surveyStatus" to a translated label will leave the template looking for a field that no longer exists.

The name of a place is more complicated than a generic interface label. Some feature names are proper names that should be preserved, some have established exonyms, and some contain directions that are important for navigation. A localization team should classify each <name> separately rather than running every value through automatic translation. A public park can have an officially bilingual name, while a field measurement station may have a protected code and a separate description. Map readers need both the useful target-language wording and an unambiguous way to identify the feature.

How BalloonStyle substitution works

A literal string is not the same as a viewer instruction

A text template can contain ordinary sentences alongside placeholder expressions. Common KML replacements include $[name] and $[description], which refer to the Placemark’s name and description. Google Earth’s ExtendedData documentation also describes references to a Data value by the record’s machine name and a reference to its human label using a /displayName suffix. These expressions are part of the template’s operating vocabulary. Their brackets, punctuation, case and key paths must be treated as protected syntax.

Suppose a template reads “Status: $[surveyStatus].” The English word “Status” can be translated. The substring $[surveyStatus] must remain unchanged if the associated Data record is still named surveyStatus. A language model that translates the key to a target-language word may create a valid XML document whose balloon fails to show its intended value. This is a semantic error in the substitution contract, not an XML syntax error, so a parser alone will not detect it.

The /displayName form adds another layer. A template can refer to $[surveyStatus/displayName], which displays the friendly label stored in the Data record’s displayName element, and $[surveyStatus], which displays the value. This allows one translation of the friendly field heading to be reused while the underlying key stays fixed. The team should not change the value simply because it is inconveniently coded; when the value is a code, consult the data owner’s domain definitions before deciding whether a human label is available or should be supplied through a separate approved field.

Shared styles make these protections especially valuable. A single BalloonStyle may serve hundreds of Placemarks, so an untested change can affect a whole map in one operation. Translation speed should come from updating the shared sentence once and validating every referenced field type. The cost of skipping the check increases with reuse. If different feature families have different Data keys, the style may need distinct templates or documented fallbacks instead of forcing one universal popup to assume fields that are absent from half the map.

What is protected beyond replacement tokens

The Placemark’s spatial coordinates, geometry type, altitude mode and projection assumptions are not part of the translation. KML coordinate tuples use longitude, latitude and optional altitude ordering; the displayed language must not cause their components to be swapped, rounded or reformatted with commas used as decimal separators. A correct localized description of a monitoring station is still wrong if the station moves to another position because an editor treated a coordinate string as ordinary prose.

KML id values, styleUrl references, style identifiers and schema field names are also references. A shared style might be called #station-balloon, and each Placemark uses that exact reference. A translator should not replace the style ID with the target-language title. Likewise, Schema and SimpleField names in structured ExtendedData can be referenced by the specialized substitution pattern that includes a type and field name. Changing those names breaks the relationship between the data and the viewer’s template.

Network links, region behavior and time settings can influence whether a feature appears at all. They should be inventoried because the translator might mistake a feature that fails to load for a missing translation. A popup can be correct in a small standalone fixture but absent in a larger map due to NetworkLink loading behavior or viewer support. Distinguish the job of translating words from the job of diagnosing spatial data distribution; the two meet at the viewer, but they have different controls and owners.

Finally, KML files can contain HTML-like markup within descriptions or BalloonStyle text. Some content is stored as escaped text, and some is wrapped in CDATA sections. These are XML encoding mechanisms, not permission to insert arbitrary active web content. A safe translation preserves valid markup and avoids adding scripts, remote resources or unreviewed links. The exact viewer may sanitize HTML differently, so test visible output and link behavior in the intended application rather than inferring safety from XML parsing alone.

A small KML fixture that shows the boundaries

This teaching example uses the conventional KML namespace URI and one shared BalloonStyle. Two Placemarks share a template that displays a translated field heading and the record-specific value. The coordinates are synthetic and the place names are invented for explanation. The two-token pattern is deliberate: a friendly label comes from the displayName element, while the value comes from the value element. The example is well-formed XML but needs additional tests for full KML profile and viewer conformance.

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>Learning stations</name>
    <Style id="station-balloon">
      <BalloonStyle>
        <text><![CDATA[
          <b>$[name]</b><br/>
          $[surveyStatus/displayName]: $[surveyStatus]<br/>
          $[description]
        ]]></text>
      </BalloonStyle>
    </Style>
    <Placemark id="station-a">
      <name>North Classroom Station</name>
      <description>Observation point beside the field.</description>
      <styleUrl>#station-balloon</styleUrl>
      <ExtendedData>
        <Data name="surveyStatus">
          <displayName>Survey status</displayName>
          <value>Reviewed</value>
        </Data>
      </ExtendedData>
      <Point><coordinates>103.824,1.329,0</coordinates></Point>
    </Placemark>
    <Placemark id="station-b">
      <name>South Classroom Station</name>
      <description>Observation point beside the library.</description>
      <styleUrl>#station-balloon</styleUrl>
      <ExtendedData>
        <Data name="surveyStatus">
          <displayName>Survey status</displayName>
          <value>Pending review</value>
        </Data>
      </ExtendedData>
      <Point><coordinates>103.825,1.328,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

A target-language version would edit the two visible descriptions, the place labels if the naming policy permits it, both displayName values, the status values if they are genuinely human-facing terms, and the ordinary words inside the template. It would preserve surveyStatus, both feature IDs, station-balloon, the matching styleUrl entries, the coordinate text and the exact $[...] expressions. Keeping the values consistent requires domain review: “Reviewed” may be an English display term for a governed workflow state and could require an approved mapping rather than a fresh guess.

Notice why translating only the template is insufficient. The viewer inserts each Placemark’s name and status into the template, so the final popup can combine a translated sentence with an English place name or English status value. That mixture might be acceptable for an official proper name, but it should be a deliberate decision. The inventory must cover both template and feature-level text. A representative fixture with two records exposes cross-feature inconsistencies that a screenshot of one Placemark would miss.

The example also helps separate well-formedness from spatial and substitution validity. An XML parser can verify that tags nest properly and attributes are quoted. It cannot by itself prove that the shared style is intended for both Placemarks, that every field name has the expected semantics, or that the viewer will render the CDATA markup in the way the author expects. Those checks need a KML-aware inspection and a viewer test. State exactly which layer passed rather than claiming the file is universally valid.

Build a translation inventory that includes all source surfaces

Start by listing every Placemark ID or another stable source identifier, its geometry type, <name>, <description>, style reference, ExtendedData Data names, friendly displayName values and raw values. For structured data, also collect Schema references and SimpleField definitions. If a shared BalloonStyle is used across a Folder or Document, record how many features depend on that style. The resulting ledger shows how one edit propagates and which fields are eligible for linguistic treatment.

Classify each text value by role. A navigational place name, interpretive explanation, measurement unit, survey status, map legend heading, safety warning and link label should not be translated with the same assumptions. A named station’s code is normally protected, while its accompanying description can be localized. A safety warning may require an approved terminology register and legal reviewer. Unit names may need appropriate local language while numeric measurements and reference frames remain fixed.

Define target language and audience before writing. A map for researchers may need technical terminology and provenance, whereas an educational walking tour needs accessible explanations. These are not competing translations of the same purpose if their canonical reader jobs differ. For one URL or KML package, choose the intended audience and preserve enough source terms for identification. Avoid copying a tourist-friendly phrase into a scientific monitoring layer where a measurement’s technical interpretation could change.

Keep a parallel record of any actual geographic or data corrections that the review uncovers. If a station is placed at the wrong coordinate or its status value is stale, that is valuable feedback, but it belongs to a separate authorized data-maintenance ticket. Do not fold it silently into the translated file and call the result language-only. Separating changes makes it possible to compare source and target data objectively, maintain attribution and roll back a faulty text release without reversing an unrelated geospatial correction.

A nine-pass workflow for quick, careful KML localization

Pass one: establish the viewer and file contract

Identify the target application, the accepted KML version and any KMZ packaging rules. The OGC KML 2.3 standard is a baseline, but implementations can vary in HTML rendering, substitutions, balloon display controls and network loading. Test a representative source file in the actual viewer before translating it. Capture what already works and any known exceptions. This prevents the language team from being blamed for a pre-existing rendering defect or a feature unsupported by the destination software.

Determine whether the user is opening a local KML file, a compressed KMZ archive or a file refreshed through a NetworkLink. Those cases affect how resources and relative paths are resolved. A translated balloon can appear correct when loaded directly yet fail when an embedded image or referenced style is absent from a packaged archive. Inventory those dependencies and keep a nonlocalized reference version as the control for later comparison.

Pass two: freeze feature and style identity

Record the XPath or another stable path to every editable surface and hash the protected attribute and geometry values. Create a report of all local style IDs and the styleUrl entries that refer to them. If one style applies to many Placemarks, a single translation can be efficient, but it also creates a large blast radius when a field substitution changes. Choose representative features from each dependent group for render testing, especially any with missing or unusually long ExtendedData values.

Capture coordinate tuples as strings and parsed numbers so that localized punctuation cannot masquerade as valid coordinate data. A user-facing display of latitude may follow a locale convention, but the KML geometry must keep its prescribed syntax. Document that distinction in the translation brief. A common failure is to ask the same editor to localize both a formatted coordinate caption and the actual <coordinates> element without marking the latter protected.

Pass three: extract exact text leaves and substitution tokens

Parse the KML rather than searching and replacing arbitrary words in the raw XML. Export <name>, <description>, eligible displayName elements, approved textual Data values and BalloonStyle prose as separate units. For each BalloonStyle text unit, detect $[...] tokens and present them as locked spans. Preserve whitespace and markup when they affect layout, but avoid making the translator responsible for XML escaping and CDATA boundaries.

A parser-driven extraction also helps with repeated labels. If “Station status” appears in fifty Data/displayName values, a translation memory may reuse the approved equivalent, but the ledger must preserve each occurrence’s feature identity. If one occurrence describes a different field, identical English wording is not sufficient reason to force the same translation. Context comes from the associated Data name, measurement source and domain definition, not from the isolated label alone.

Pass four: translate meaning with location context

Give the linguist a map preview and a concise field definition for each string. A word such as “bank” may mean a riverbank, an institution or a raised border depending on geography. The surrounding feature category determines the correct target-language term. Proper names need an explicit policy: preserve official spelling, use an established translated name, or provide both when the format and audience support it. Do not silently transliterate identifiers that researchers use to cross-reference field records.

Review directions and safety instructions with special care. “Keep left of the path” can be dangerous if “left” is accidentally inverted or if the instruction is adapted for a different viewpoint. A historical placemark description may include dates, locations and named sources; translating them must not convert approximations into exact claims. The language reviewer should be able to explain how the target text preserves who, where, when and what was observed, not just whether the grammar sounds natural.

Pass five: reinsert text without changing the KML structure

Use an XML serializer or controlled element replacement to insert approved text. Preserve the namespace, element order required by the format, style IDs, ExtendedData machine names and geometry. If the text includes characters requiring XML escaping, let the serializer handle them. If an implementation uses CDATA for a BalloonStyle HTML fragment, preserve valid CDATA boundaries and test that the inserted text cannot close the section unexpectedly. Blind byte-level substitution is fragile when languages use punctuation and characters different from the source.

Treat HTML inside balloon text as a separate markup surface. The allowed visible words can change, but the structure, destination links and any content-security rules must be checked. A translated sentence may require different line wrapping or spacing, yet it should not create active content or load an unapproved remote resource. The KML file is a document consumed by software; it should be handled with the same care as any other structured source that can contain potentially interpreted markup.

Pass six: validate XML, KML and substitution references

Begin with a basic XML parse. Confirm there are no unclosed tags, illegal characters or broken entity references. Then run any available KML schema or application-specific validation for the chosen profile, remembering that a validator’s coverage is limited. Compare protected values against the source using a structural diff. The target file should contain the same intended Placemarks, styles, feature references and geometry, with changes limited to authorized human-facing content.

Create a substitution inventory for each BalloonStyle. Extract every $[...] expression and confirm that standard tokens are supported by the intended viewer and that custom Data tokens refer to an actual Data name or documented Schema field. Compare the token sets before and after translation. If a target string introduces a new token or loses one, fail the build for review. This check catches a whole class of errors that a generic XML parser will never detect, even when the rest of the file is perfectly well-formed.

Pass seven: open the file and inspect real balloons

Use the destination map viewer to open a feature from every shared style group. Check that the popup shows actual names and values rather than unresolved $[...] text. Compare its meaning with the source and verify that units, status values and links are intelligible. Long target-language lines may wrap around images or exceed the available balloon width. Test both a short record and a record with the longest realistic name or description.

Inspect spatial context at the same time. The translated Placemark should appear at the same location with the same geometry and map layer behavior. A textual status might indicate an observation site is closed while the geometry remains a route line; these are logically separate elements. If a viewer hides balloon content because of unsupported markup, record the renderer limitation rather than altering source data to force a display. A different safe presentation may be needed for that client.

Pass eight: evaluate accessibility and reader comprehension

A popup should be understandable when read aloud or navigated with assistive technology where the viewer supports it. Check whether HTML headings, links and labels produce a sensible reading order. A friendly Data/displayName might be visually clear but meaningless when a screen reader announces only a raw code. Consider whether to add an approved explanation in the description or a corresponding accessible output in the surrounding application. Do not claim that KML itself guarantees accessibility across every consuming viewer.

Ask a target-language reader to locate one feature, interpret a status and explain the next action implied by the popup. This is more useful than asking whether the translation sounds nice. If the reader mistakes a measurement for a warning or confuses the place name with the status field, the label hierarchy needs repair. Record these observations and the source contexts that caused them so the same ambiguity is not repeated across the rest of the map package.

Pass nine: release a traceable, reversible localization package

Publish the target-language KML or KMZ through the project’s controlled delivery process, keeping the source and prior approved translation intact. Store the language tag, translation version, validator result, viewer version, protected-data diff and screenshots for representative features. If the map is refreshed automatically, make sure the localization is part of the authorized update chain and not a side file that will be overwritten by the next network refresh.

A rollback plan should restore the former wording without silently reverting an independently approved data correction. Track reported defects by category: wrong meaning, missing data substitution, bad styling, broken links, incorrect geometry or unsupported client behavior. Repair the layer that actually failed. A reader will experience them all as a broken map, but the responsible technical teams need precise evidence to fix them efficiently.

Diagnostic cases and concrete repairs

A placeholder appears literally in the balloon

The popup shows $[surveyStatus] rather than the expected value. First confirm that the Placemark actually has an ExtendedData record with exactly that Data name and an appropriate value. Then confirm the shared style is applied and the viewer supports the substitution. Compare case and punctuation; a localized key in the template may not match the stored machine name. Restore the protected token or correct the data reference under the approved schema, then retest more than one feature that shares the style.

The label translates but the value remains in English

The expression $[surveyStatus/displayName] can show a translated heading while $[surveyStatus] inserts an English value. This is not necessarily a broken substitution: it means only one source surface was localized. Decide whether the value is a human label, an immutable code or an official term. Translate an approved human-facing value consistently across relevant records, or provide a clearly labeled explanation without rewriting a code. Do not infer that every value child is safe to edit merely because it is displayed in a balloon.

A coordinate moves after the language pass

A decimal comma or reordered tuple may have been inserted into a KML coordinate string. Compare source and target geometry values byte-for-byte and as parsed numeric tuples. Restore the original longitude, latitude and altitude sequence. If a user-facing coordinate caption needs locale formatting, generate that caption separately from the protected geometry. Do not attempt to make the underlying KML coordinate syntax follow the conventions of the translated sentence; the coordinate parser has its own contract.

The shared style works for some features but not others

A generic BalloonStyle may reference a Data key that does not exist on every Placemark. Identify which feature families use the style and group their available field names. Provide a style appropriate for each supported schema or a documented fallback for absent values. Avoid adding invented placeholder values just to fill the screen, because readers may interpret them as observations. Every template branch should have a representative test feature in the release evidence.

The popups show duplicate text

A viewer may render default ExtendedData output alongside a description, or a project may repeat the same information both in the description and in a custom BalloonStyle. Inspect what the source viewer actually renders and which presentation surfaces are active. Remove unintended duplicate display only through a documented template or content edit that preserves the underlying data. Do not delete ExtendedData records merely to suppress a visual repetition; those records may be used by analysis tools.

A localized field name breaks an external lookup

Someone translated Data name="surveyStatus" to a human-friendly phrase. The popup may fail because the BalloonStyle still uses the original key, and a downstream script might rely on the unchanged machine field. Restore the original Data name and put the translation in displayName. Retest both the viewer and any documented extraction process. This is a useful general pattern: a stable key serves integration, while a separate label serves the reader.

HTML markup is visible instead of rendered

The intended bold label appears with literal angle-bracket tags, or the viewer discards some markup. Inspect whether the text was escaped or wrapped in CDATA as the renderer expects, and check its supported HTML subset. Repair the encoding and template rather than blindly replacing every &lt; with a raw angle bracket. Rendering differences may be viewer-specific; record the version and choose a safe minimal presentation that works for the target environment.

The popup contains a link to the wrong language page

An embedded link may refer to an English report while the surrounding explanation promises a translated resource. Verify whether the campaign or map owner has an authorized localized destination. Preserve stable URLs until that owner approves a change, then test both routing and the linked page’s meaning. A language reviewer may correctly identify the mismatch but should not silently redirect navigation. Broken provenance and link integrity can be as damaging as incorrect labels in educational maps.

A place name is translated into a different location

Machine translation sometimes treats a proper name as a descriptive phrase or substitutes a familiar geographic name. Compare the localized name with official signs, local gazetteers or the dataset’s agreed naming standard. Keep the feature ID and coordinate stable, and choose a recognized name or bilingual form suitable for the audience. Avoid letting a readable label become a new geographic assertion. The source and translated name should still point readers to the same feature.

The popup hides an important warning after truncation

A safety note that appears near the end of the description can be pushed out of the visible area by longer target-language wording. Test the longest relevant text in the real viewer and examine whether the warning is still prominent and complete. Condense optional background information before cutting a critical condition. If the balloon template cannot present the warning safely, add an approved alternative display or mark the localization release as blocked for that client.

A KMZ package loses its relative image reference

The original source KML may refer to an image file packaged alongside it. A translation workflow that exports only the edited KML will omit the companion asset, so the balloon loads text but shows a broken illustration. Inspect the KMZ archive entries and relative paths before and after packaging. Keep asset names stable unless a coordinated packaging change updates every reference. Verify with a clean extraction or direct target-viewer open, not only in a developer workspace that still contains the missing files.

The translated local file looks correct until the viewer refreshes its remote source. Determine which resource the NetworkLink actually loads and whether it returns language-specific content. A translation delivered as a one-off local patch may be overwritten on refresh. Repair the source generation or delivery configuration through its owner, ensure the authorized locale variant is served, and recheck the protected data. Do not repeatedly edit the client’s cached copy as though it were the canonical map.

The displayName references the wrong Schema field

Structured ExtendedData uses Schema and SimpleField relationships that differ from simple Data records. A template referring to the wrong type or field can produce an empty label while the XML remains well-formed. Inspect the Schema names, SimpleField names and SchemaData references, then compare the documented substitution form against the actual field. Translate a SimpleField’s human-readable displayName, not its machine name, unless a separate schema migration has been approved and every dependent consumer updated.

A target script appears in the wrong order

A right-to-left Placemark name can render confusingly when combined with Latin coordinate references or English identifiers. Test the target text in the actual viewer and consider whether the host application supports appropriate direction handling. Preserve machine IDs and numerical geometry, and avoid inserting invisible controls without understanding their behavior in this client. If a safe presentation cannot be achieved in the intended viewer, document the compatibility limit rather than hiding the problem behind a different screenshot.

Changed-context transfer exercise with worked answer

Imagine a regional flood-preparedness map distributed as a KMZ archive. It has eighty river-monitoring Placemarks and three shared BalloonStyles. Each popup shows a place name, last inspection date, risk status and a public safety instruction. One style references $[riskStatus/displayName] and $[riskStatus]; another uses a schema-qualified field reference. The team is asked to translate the public-facing text for a second language while preserving the map’s certified monitoring data and automatic refresh behavior.

A colleague proposes changing the riskStatus Data name to the target-language word, translating the entire coordinate list into local decimal conventions, and changing the shared style ID so it looks more natural. Another colleague suggests preserving all data but translating only the shared template sentence. Your task is to explain why both plans are incomplete and design a test set that is small enough to run quickly but broad enough to catch a dangerous mistake in a safety-oriented popup.

The correct plan freezes feature IDs, geometry, style references, schema names and substitution tokens. It translates the approved shared prose, appropriate displayName labels, relevant feature descriptions, warnings and any explicitly authorized human-facing status values. It does not change riskStatus or the coordinate syntax. For the schema-qualified style, it checks the full type-and-field reference separately. It also verifies that the refresh source delivers the localized file and that the KMZ still includes the images or other assets used by the balloons.

A good test set includes one feature from each style family, a feature with a missing or unknown status, the longest warning, and an example near a sensitive river boundary where moving the coordinate would matter. Compare parsed geometry and protected references against the source, then open the KMZ in the actual viewer and ask a target-language reader to interpret the risk instruction. If any warning becomes ambiguous or hidden, fail the release. The same method transfers to archaeological tours or campus navigation maps, with the level of safety scrutiny adjusted to their real-world consequences.

Practical review checklist

  • Identify the intended KML profile, viewer and whether the package is KML or KMZ.
  • Inventory every Placemark, style reference, Data field, Schema field and displayed text leaf.
  • Lock feature IDs, coordinates, style URLs, field names and every $[...] substitution token.
  • Translate approved names, descriptions, displayName values and template prose with context.
  • Keep status codes and measurement values stable unless the data owner approves a semantic mapping.
  • Parse the resulting XML and run KML-aware substitution and style-reference checks.
  • Confirm all shared styles render with representative features, including long and missing values.
  • Inspect HTML escaping, links, accessibility, bidirectional scripts and packaged resources.
  • Verify NetworkLink refresh behavior, source provenance, change logs and rollback readiness.

Limits and conclusion

KML is an interchange language, not a guarantee that every viewer supports every balloon-template feature in the same way. OGC KML 2.3 defines a standards framework, while viewer documentation describes implementation-specific behaviors and examples. A document that parses as XML may still use unsupported substitutions, have unresolved style references or show text differently across platforms. A change that works in one desktop client is not sufficient evidence for another client or for a web-based presentation that sanitizes markup differently.

This guide is also not authorization to alter spatial, safety or public-health data. Place identities, coordinates, inspection dates, risk codes and link destinations may have independent governance and legal consequences. Translation can clarify their display and reveal inconsistencies, but corrections to the underlying dataset require a separately owned and reviewed change. The strongest releases preserve that distinction in the audit trail so readers can trust both where a feature is and what its popup says.

The practical method is simple even though its consequences can be serious: locate the text source, lock the references, translate meaning, compare the protected structure, resolve placeholders, render in the actual viewer and test a changed context. A well-designed shared BalloonStyle allows one linguistic improvement to help many Placemarks without multiplying errors. That is how the map can become easier to understand in another language while remaining the same map.

Frequently asked questions

Is a KML BalloonStyle token ordinary text that can be translated?

No. Expressions such as $[name] and $[surveyStatus] are viewer substitution instructions. Keep their syntax and referenced machine names unchanged.

What is the difference between Data name and displayName?

The Data name identifies the field for references; displayName is its reader-facing label. Translate the latter when appropriate and preserve the former.

Can a Placemark name ever be translated?

Yes, when the project’s naming policy allows an established translated or bilingual name. Keep the feature identity and geometry stable and check official usage.

Does well-formed XML prove a KML balloon will render correctly?

No. XML parsing checks syntax, not all KML semantics, shared style references, substitution resolution or viewer-specific HTML rendering.

Why should coordinates be excluded from language export?

They are typed spatial values with defined ordering and syntax. Localized punctuation or swapped components can move a feature or make geometry unreadable.

How is $[surveyStatus/displayName] different from $[surveyStatus]?

The first requests the friendly field label, while the second requests that Data record’s value in a supporting viewer.

Do all viewers support the same rich HTML in balloons?

No. Viewers differ in markup and substitution support. Use safe content and test the exact destination application and version.

What should happen if a shared style references a missing field?

Report the unresolved reference and decide whether to provide a documented fallback or a more appropriate style. Do not fabricate observational values.

Only when the responsible owner approves the destination change and verifies routing and provenance. Links are operational dependencies, not just prose.

Why test a KMZ package after translation?

KMZ can include dependent files such as images. A correct KML text file may still fail when the packaged resource paths or archive contents are missing.

Authoritative sources

Verified internal reading suggestions

Human SEO metadata

SEO title: KML 2.3 BalloonStyle Translation QA | eduKateSG

Meta description: Translate OGC KML Placemark balloons and ExtendedData labels without breaking substitution tokens, feature IDs, map coordinates, styles or KMZ delivery.