How can you translate OpenStreetMap PBF data for an international map or location guide without moving a road, disconnecting a bus route or replacing the legal identity of a place? An .osm.pbf file is a compact binary representation of OpenStreetMap objects. It combines structured geography with many human-facing name and description tags. Some text can be shown in several languages, but most identifiers, tag keys and relation references should remain exact.
Searches for OSM PBF format explained, OpenStreetMap nodes ways relations, BlobHeader and PrimitiveBlock, DenseNodes delta encoding, string tables, granularity coordinates, name language tags, multilingual OSM maps and PBF translation tend to mix two very different jobs. One job decodes a technical data file; the other chooses the right language for map labels. A successful project must do both without confusing them.
This longform educational guide explains the underlying OSM PBF file structure and the language decisions that arise in mapping applications. It is for translators, geographic data specialists, software engineers, educators, community mappers and publishers. Examples are illustrative and do not replace OpenStreetMap community tagging rules, local naming practice, licensing obligations or official geographic records. The key principle is simple: translate explanations and appropriate labels, not the data relationships that make a map work.
A map dataset is more than a picture
An OpenStreetMap dataset records editable geographic objects and their descriptive tags. A rendered map is one interpretation of those objects, made by software and style choices. The same data can support different languages, scales or applications without requiring the underlying street geometry to be rewritten.
If a road label is translated, the path should still connect the same nodes and refer to the same feature. Otherwise the work has changed the geography rather than merely helping a reader understand it.
Begin by separating geometry, object identity, tagging and display language. The safe localization boundary normally lies in the last two, and even tags require careful rules.
PBF is a compact binary transport format
OpenStreetMap PBF uses Protocol Buffers to encode OSM objects in a compressed, structured form. It is an alternative to verbose XML representation, not a different geographic truth. A PBF file cannot be treated as a text document even though many of its encoded tags eventually decode to readable strings.
A generic translation tool that opens the raw bytes and replaces words could invalidate lengths, message fields or references. The resulting file might fail to open or, worse, parse partially and silently lose information.
Use a PBF-aware reader to extract approved human-facing labels and a writer to produce any authorized transformed dataset. Keep the original bytes and verify objects after reserialization.
Nodes represent geographic points
A node has an identifier and coordinates; it can also have tags. A node might represent a bus stop, a shop entrance or an untagged point used to define a road. Being a node says how it is stored, not what real-world object it represents.
Translating the name of a bus stop does not authorize moving its latitude or longitude. Even a small coordinate error can change which side of a road the point appears on and confuse wayfinding.
Keep node IDs, coordinates and references stable. Translate an approved display name while preserving alternative names and language qualifiers where the tagging scheme supports them.
Ways connect ordered node references
A way is an ordered list of node references, often used for roads, paths, boundaries and building outlines. The order may matter for geometry and for directional interpretations. Ways are not sentences whose words can be rearranged to improve grammar.
A one-way road may appear in a display as a labelled line. If a converter reverses node order while leaving directional tags unchanged, routing behaviour can change even though the road still looks plausible.
Check that every way still refers to the same nodes in the same order when a transformation is meant to be language-only.
Relations connect other map objects
Relations assemble nodes, ways or other relations into structured geographical concepts. They can represent routes, multipolygons, restrictions and other relationships. Members have types, identifiers and roles, so a translated caption must not replace the formal relationship.
An international bus route might need a different public label. If the translation drops a relation member or changes its role, the route may become disconnected or a restriction may stop working.
Keep membership, role semantics and ordering consistent with the relevant relation type. Test a route or multipolygon in suitable mapping software after export.
Object identifiers must remain exact
OSM node, way and relation IDs are stable technical references within the data system, not local-language labels. The PBF design accommodates large integer identifiers. Rounding, formatting or converting them to ordinary numerals with separators can break joins across files and APIs.
A spreadsheet that stores a large identifier as a floating-point number may silently change its final digits. Later, a relation could point to an object that does not exist under that rounded ID.
Keep IDs as exact integers or safe text representations in intermediate systems. Compare identity sets before and after any localization pipeline.
The overall file has framed blocks
An OSM PBF file is organized as a sequence of file blocks. A length prefix precedes a BlobHeader, which describes the next Blob. This framing helps readers move through the file. It is a technical envelope, not a language string to rewrite.
If a naïve editor changes a byte inside the length prefix, the reader may begin the next message at the wrong location. None of the place names need be mistranslated for the file to become unusable.
Work at the decoded object level. Let tested format libraries manage frame lengths and serialized messages rather than manually editing the binary file.
OSMHeader and OSMData serve different roles
OSM PBF commonly uses OSMHeader for high-level file metadata and OSMData for actual geographic objects. Data blocks contain PrimitiveBlock messages. A reader must inspect the relevant file-header features before interpreting later data.
An editor may mistake a source attribution or replication field for a map feature and insert a translated place name there. That would confuse metadata about the dataset with information about a geographic object.
Preserve required features, source information and replication details. Translate descriptions in documentation, while keeping structural type names such as OSMHeader and OSMData unchanged in the file.
Required features are parser commitments
The PBF header can declare required and optional features. A required feature means that a reader must understand it to interpret the file properly. These names are machine-facing tokens, not ordinary vocabulary.
If required_features includes DenseNodes, translating the string into another language will not teach the parser the translated concept; it may instead make the feature unrecognizable.
Do not localize feature flags. Verify that every declared required feature is supported by the tool used to extract or serialize the file.
PrimitiveBlock groups actual entities
An OSMData block holds a PrimitiveBlock with a string table and primitive groups. This arrangement allows nodes, ways and relations to be packed efficiently. It differs from a plain list of name-value objects because many strings are stored once and referenced by index.
A translation that modifies the string table without updating references could attach the wrong value to many map features. One accidental change can spread farther than a single displayed label.
Translate at the decoded semantic layer, then rebuild the string table through a format-aware writer. Compare object tags after export.
The string table is shared within a block
OSM PBF uses a StringTable to store strings such as tag keys, tag values and relation roles. Other messages refer to entries by index. A visible word may therefore be shared by many objects or have different meanings according to the tag key using it.
Replacing the string primary everywhere could corrupt a highway classification rather than translating a road name. The same sequence of letters may be a stable token in one context and ordinary language in another.
Decide translation eligibility by field and tag semantics, not by raw string matching. A shared table is a compression technique, not a bilingual dictionary.
Tags are key-value assertions
OSM tags describe properties through keys and values. A tag such as amenity=school is a data statement recognized by mapping software. Its words may look English, but they function as technical keys and controlled values in a community schema.
Replacing school with a translated everyday noun can make a school disappear from an application’s point-of-interest search. The place still exists geometrically, yet the software no longer recognizes its category.
Preserve key and value tokens governed by OSM tagging conventions. Translate the displayed category into the user’s language in an application legend or user interface.
Name and name:language fields are different
A name tag can contain the primary local or conventional name under OSM practices, while language-qualified name tags can carry additional linguistic variants. Those fields should not be treated as a command to overwrite the original name with an outsider’s translation.
An international map may want a Japanese, Arabic or English label for the same city. That can be a display selection rather than a replacement of the locally used name.
Review existing names and community guidance. Prefer correctly qualified names and renderer language preferences over destructive rewriting of the name tag.
Transliteration is not the same as translation
Some names can be represented in another script without translating their literal meaning. That is transliteration or transcription. Others have established exonyms used in different languages. Place naming involves history, usage, local standards and community sensitivity.
A street name based on a person’s surname should not automatically be translated into the dictionary meaning of its components. Equally, a long-established exonym may be appropriate for a particular audience while the local name remains primary.
Document whether each label is an official name, local name, transliteration, exonym or descriptive translation. Do not invent names simply because no localized tag exists.
Multilingual maps are usually a rendering problem
A map application can select language-specific labels at display time while keeping OSM geometry and identifiers unchanged. This approach is usually safer and more flexible than exporting a different geographically altered dataset for each language.
Visitors from different countries may choose different interface languages but still need identical roads, buildings and transit routes. Separate the map’s data keys from the captions it shows.
Test the language fallback rules: preferred-language name, available alternative, and appropriate original name. Verify that absent translations do not cause unnamed or misidentified places.
A missing translated name is not permission to guess
A map database may not contain a name in every language. Generating one automatically can create plausible but incorrect toponyms, especially when the local name has a historical or cultural form not captured by simple dictionary translation.
For a small town, an automated English label may be a literal rendering that nobody uses. Users might then search unsuccessfully for that invented name in official sources.
Where the evidence is absent, retain the established source name and add a clear explanation if needed. New tags should follow community guidance and ideally local verification.
DenseNodes use compact delta encoding
PBF can store nodes in a dense representation using arrays of differences rather than full repeated numbers. This saves space, but it means the raw encoded integers are not the same thing as the reconstructed node IDs and coordinates.
A developer who changes one delta value can affect every later reconstructed value in that sequence. A translation workflow operating on raw bytes is therefore especially dangerous.
Decode the complete node sequence before selecting labels for translation. Re-encode using a trusted library and compare reconstructed identities and coordinates, not only encoded byte counts.
The keys_vals stream includes delimiters
Dense node tags may be stored as a packed sequence of string-table indices, with a zero marker used to separate the tags belonging to different nodes. This marker is structural. Removing it can shift subsequent tags onto the wrong map objects.
If a translator-facing export shows a flat list of tag strings without node boundaries, an editor may combine two adjoining name fields, unknowingly assigning one name to another feature.
Use a decoder that associates every tag with its originating node ID. After re-encoding, compare tag dictionaries per object.
Ways and relation members can be delta-coded
References to way nodes and relation members may be represented through differences between consecutive IDs. The point is compact encoding, not changing the meaning of the referenced objects. A single incorrect delta affects subsequent reconstructed references.
An international cycling route could show a broken segment after a careless low-level edit, even though the relevant language text was correct. Its member identities or way geometry were altered.
Treat decoded object references as immutable during translation-only work. Verify membership lists and consecutive node sequences against the source.
Coordinate granularity is a scale definition
PBF node coordinates are often encoded as integer values combined with a granularity and offsets. The specification describes conversion to degrees using a nanodegree scale. Changing a granularity value without transforming the integers moves many positions at once.
A point representing a school might be shifted by a huge distance if its encoded latitude is interpreted directly as degrees. A language label can be perfect while the position becomes nonsensical.
Use the documented formula and compare known coordinates. A multilingual export should preserve real-world positions within intended numeric precision.
Offsets and signs require care
Latitude and longitude reconstruction may include separate offsets, as well as granularity. Signed integers and delta values have precise roles. This is not a place for a natural-language translation of positive, negative or direction.
A negative encoded value may be perfectly valid after applying the correct offset. A developer who discards the sign as a formatting issue can move a feature to a different region.
Verify northern and southern, eastern and western examples, including points near zero. Preserve the integer semantics and use scientific units consistently.
Timestamps are not map labels
OSM object metadata can include timestamps represented using date granularity. A timestamp identifies when a version of an object was recorded or edited, not when a physical road was built. Translating a date for display does not justify changing its value.
A reader may mistake an object edit date for the opening date of a bridge and produce a misleading tourism guide. Those two facts have distinct sources and confidence levels.
Use metadata timestamps for provenance and currency, not unsupported historical claims. Keep temporal values stable and document display-time date formatting separately.
Versions and changesets describe history
OSM objects can have version and changeset metadata. These fields help communities trace edits and understand when and how data changed. A translation of a feature description must not rewrite the object’s edit history or impersonate an original contributor.
Suppose a newly localized road label is published in an app. The app should not describe that display change as an OSM community revision if the underlying OSM object was not edited.
Distinguish source history from local presentation changes and respect contributor attribution and applicable licensing.
Replication sequence identifies dataset currency
Some PBF files carry replication-related metadata used by tools to synchronize updates. A sequence number or source URL is not ordinary text to be translated; it helps identify which point in the update stream the file represents.
Changing an update source while keeping the old sequence can make synchronization incoherent. A downstream system might skip updates or try to apply changes from the wrong stream.
Keep replication fields intact when appropriate, and document any deliberate change to source or update strategy as a technical operation separate from localization.
A boundary box is an index hint, not a license
A PBF header may include a bounding box indicating approximate geographic coverage. It helps describe the extract, but the file contents and extraction procedure remain authoritative for exact object relationships.
A translator may write that a regional extract covers all roads within a city, while the file’s bbox or clipped content does not fully support that assertion.
Compare claimed coverage with the actual extract and note boundary limitations. Preserve numeric bounding values and clarify whether geometry outside the region may still be needed to complete relations.
Partial extracts can break relationships
Regional PBF extracts sometimes omit nodes or relation members outside their selection or clipping rules. This matters for transport routes, boundaries and large multipolygons. An incomplete relation is not necessarily a translation error, but it should not be advertised as a complete object.
An international trail guide may show a route ending unexpectedly at the edge of an extract, not because the route physically stops but because the dataset omitted its continuation.
Check extract completeness and relevant dependencies before creating route statements. Use an appropriate full dataset or document the extent.
Road classification tokens have special meanings
OSM highway values describe categories according to mapping conventions, not simply everyday judgements of road quality. For example, primary in a technical tag is a class within the road network and cannot be freely replaced by a translated adjective.
A translator who rewrites highway=primary as something meaning excellent road changes the category and creates a false description for travellers.
Keep stable tokens inside the dataset. Explain their practical role in target-language educational material and consult current tagging conventions for region-specific nuance.
Access restrictions must not be softened
OSM can represent legal or practical access information for routes and features, including different modes of travel. These are important for routing and safety. Translating access-related tags as though they were friendly suggestions can mislead users.
A path marked private should not become open to visitors simply because the map wants a welcoming label. Similarly, foot access and motor-vehicle access are not interchangeable permissions.
Preserve controlled access tags and their values. Explain applicable restrictions accurately and remind readers that on-the-ground signs and local law may supersede or update map data.
One-way streets and routing direction
Ways have ordered nodes, and routing can depend on one-way and other direction-related tags. Changing order, tags or relation roles may alter legal and computational routes. This is not merely a cartographic display choice.
A translation that reverses a street’s arrow for visual aesthetics could tell drivers to travel against permitted direction. A plausible map image would then be a safety issue.
Validate routing on representative roads, bridges, turn restrictions and roundabouts after any data transformation. Do not let label layout mutate topology.
Multipolygons define areas through relations
Some complex areas are represented by multipolygon relations with members that define outer and inner rings. A role such as outer or inner is structural vocabulary in a relation, not a natural-language description to replace.
If an inner member is changed or removed, a hole such as a courtyard may be filled in. A map can still render a polygon while misrepresenting what is inside the boundary.
Preserve relation member roles and geometry. Use a bilingual explanation of how an area is assembled without editing the role strings in the file.
Public transport routes require membership
Transport relations can group routes, stops or ways according to local tagging conventions. Their members and roles matter for route reconstruction. A translated destination label is a different concept from the route membership list.
A bus route advertised in an international guide might have a readable destination but disconnected segments if a translator-facing export dropped unlabelled members.
Compare member counts, types and references and inspect an example route end to end. Keep any localized passenger-facing description separate from data linkage.
Search depends on names and stable IDs
Search tools may index primary names, alternative names, language variants and categories. Editing just the printed name can be enough for a user interface, but replacing underlying IDs or category keys can destroy search joins and routing references.
A visitor might search for a local station by its established name or an exonym. A sensible multilingual app can present both without treating them as different stations.
Test exact-name search, alternate-name search and object retrieval across languages. Preserve canonical object identity and specify name fallback order.
OSM map data are community-maintained
OpenStreetMap is built and revised through contributors and organized conventions. A name or access status may be current, stale, disputed or incomplete. Localization should not turn community-provided data into a claim of official government verification.
A translated city guide should avoid saying that every footpath is legally accessible just because a tag suggests it. Data currency and local regulations remain relevant.
Use source and date information where available, verify consequential claims separately, and retain caveats about completeness and update frequency.
OpenStreetMap licensing and attribution
OSM data come with licensing and attribution obligations. A translated map or derived dataset does not become unrestricted simply because the labels appear in another language. Source attribution and rights should be addressed before publication or redistribution.
A commercial publisher may create a beautifully localized map while forgetting to credit the data source or consider database share-alike requirements when applicable.
Check the current OpenStreetMap Foundation license guidance and project-specific use. Keep attribution visible and distinguish data licensing from rights in third-party imagery.
Privacy and sensitive mapping
Some mapping contexts touch private residences, vulnerable communities, infrastructure or sensitive local knowledge. A translator may see a name or identifier that can be copied technically but is not appropriate to amplify indiscriminately.
Publishing a new-language guide can expand the audience for a location claim, including an outdated or disputed one. Translation can increase reach without increasing evidence quality.
Follow publication policies, avoid identifying private people from incidental data and seek responsible review for sensitive content. Separate legitimate corrections from linguistic edits.
A hypothetical school tag example
Consider a synthetic point representing a school, with amenity=school and a locally used name. The category token tells software the feature is a school; the name tells people what it is called. A bilingual app can display a translated category while preserving the exact tag.
If a translator changes the category value to a dictionary translation, the school may vanish from a search filter. If they replace the local name with an invented English phrase, users may not recognize the place.
Keep amenity=school and stable identifiers. Use verified language-qualified name variants where appropriate and maintain fallback to the established name.
A hypothetical way and node-order problem
Imagine a road represented by five ordered node references. A language-editing export sorts the associated records alphabetically by street name, then accidentally rewrites the way node order. The road may fold back on itself even though all five node IDs still appear.
This example shows why counting objects is not enough. Referential integrity includes sequence and semantics, not just the total number of references.
Compare complete ordered node-reference arrays before and after export. Rebuild a route through the road to confirm the geometry and direction are unchanged.
A hypothetical boundary translation problem
Imagine an administrative boundary stored through a relation with outer members and labels in more than one language. An editor wants to create a localized region map and translates the word outer inside the relation role field. A parser that recognizes only the original role may no longer assemble the boundary correctly.
The printed caption is more readable, but the mathematical area can fail to render. That is a data transformation error, not a linguistic improvement.
Preserve role tokens and translate an accompanying description of the boundary. Test the polygon topology and area in a capable GIS reader.
A coordinate formula explained in plain language
The PBF representation combines stored integers with a granularity and offset, then scales the resulting number of nanodegrees into degrees. In simplified terms, latitude equals one-billionth times the sum of the latitude offset and granularity multiplied by the encoded latitude. Longitude has the analogous rule.
Using the encoded integer directly as a degree value ignores this scale. Even a smaller mistake in granularity can shift every point enough to damage local navigation.
Teach the transformation with a synthetic known point, and compare the resulting coordinate to the original map. Never alter the underlying numbers to make the explanation easier.
A string-table index example
Suppose a primitive block stores the word Main once in a string table and several features reference it. That is a storage optimization. It does not prove that every occurrence is the same kind of name or should receive the same translation.
One feature might use Main as part of a street name while another uses a different key with its own convention. Global replacement ignores context.
Decode to complete key-value pairs per object before making translation decisions. Rebuild the table afterward and verify the actual tag dictionary on each object.
A route relationship example
A regional walking route may use many way members plus a route relation. Translating its description could be useful for visitors, but the route may cross the edge of the extracted file. If missing members are ignored, the guide might present a partial path as a complete route.
Use the full relation definition, member references and coverage information before publishing route directions. A data extract is not automatically a route plan.
Test start and end connections, path continuity and member identity. Keep the translated route name separate from the structural membership of its ways.
Build a field-by-field bilingual glossary
A good glossary distinguishes node, way, relation, tag, key, value, name, language-qualified name, identifier, string table, delta, granularity, bounding box, route member and replication state. Each entry explains both the ordinary meaning and its machine-facing role.
For example, way is a technical object type, not necessarily a pedestrian path; relation is a structured set of member references, not a human relationship. These distinctions help language specialists avoid plausible mistakes.
Publish the glossary as a companion document or interface help, not by replacing technical keywords inside the binary file.
A robust workflow for language-only localization
Keep an untouched PBF source and record its checksum, timestamp and provenance. Parse the file and inventory object counts, IDs, coordinates, tag dictionaries and relation memberships. Decide which human-facing values are authorized for localization and whether they belong in the dataset or only in an application.
Translate approved strings with field context and stable object references. Re-encode through a tested PBF writer only if there is a real need to produce a modified data copy.
Read back and compare every numeric and referential invariant. Recalculate representative geometry and test map search and routing before release.
Why a file opening successfully is insufficient
A data pipeline can produce a syntactically readable PBF whose tags point to the wrong objects. A map renderer might silently ignore unknown keys, omit incomplete relations or apply fallback names that hide mistakes. A smooth-looking map is not proof of preserved data meaning.
Compare IDs, coordinates, geometry sequences, relation memberships and tag dictionaries. Test special cases with multilingual names, negative coordinates and missing alternative labels.
Have a geographic-data reviewer inspect the dataset and a language reviewer inspect the display. These are complementary forms of quality assurance.
An international map handoff worth trusting
A trustworthy localized map package links the original data source to its translated explanations. It records the source extract, rights and attribution, technical reader or writer, allowed tag edits, language mapping and verification results. Users can then distinguish source geography from translation decisions.
The goal is a multilingual map in which the same stop is the same stop, the same path follows the same geometry and the same access rule carries the same restriction across languages.
Preserve uncertainty when data are incomplete. A clearly documented gap is preferable to a fabricated local name, invented road connection or false claim of official status.
Why tagging conventions should be checked locally
A vocabulary entry may be documented globally while practical usage varies by country, feature type or community consensus. This is especially true of named places, addresses and transport networks. A translation reviewer should consult the tag’s definition, local examples and community practice rather than imposing a dictionary equivalence.
If two plausible names are in use, record their context instead of deleting one to make the data look neat. The locally used name may be preferable in a map, whereas an international exonym may be useful in search.
Always distinguish a disputed naming decision from a software bug. Linguistic certainty cannot be manufactured by editing a PBF string table.
Inspect data after conversion through two independent views
An object-level diff can reveal exact changes to tags, references and coordinates. A geographic visualization can reveal consequences in context. Neither is sufficient on its own. A map can look correct while a relation member is missing, and a diff can be hard to understand without knowing the place.
Choose sample locations with ordinary names, non-Latin scripts, multilingual labels, complex transport routes and administrative boundaries. Compare source and target across these cases.
Add checks for number of ways, nodes and relations, plus per-object names and feature tags. Then test search and rendering in the target-language application.
Protect numeric precision across data systems
Intermediate spreadsheets, JSON exports and analytics tools may store numbers differently. Large OSM IDs and dense coordinate integers should not be rounded through an unsafe numeric type. This is not an obscure implementation detail: one changed ID can disconnect an important map object.
If a system cannot represent all required 64-bit integers exactly, carry identifiers as strings or use a safe integer representation. Reconstruct them before writing the PBF.
Run exact equality checks for original and exported identities. Never rely on visual spot-checking of a long identifier in a formatted spreadsheet.
The difference between user-interface translation and database modification
In a reader application, it may be sufficient to translate menu labels, category descriptions, tooltips and appropriate place names. That often provides an excellent multilingual experience without rewriting any OSM data. Direct modification of the PBF requires stronger justification and technical review.
A travel app could offer directions in several languages, but the network graph behind those directions remains the same. Keeping those layers separate also makes corrections easier.
Treat the original geographic dataset as a source of truth for the application rather than a draft that every translator must edit. This is an architectural choice that improves safety and maintainability.
Make failure examples part of teaching
Technical training improves when learners see how small changes create large effects. A language edit to name:fr may change only a display label; an edit to the string table’s indices may reassign many tags; an edit to granularity may shift whole regions; and a wrong way reference may disconnect a road.
These are not equally serious operations even though all can involve short strings or integers in an editor. A professional workflow classifies their risks before changes occur.
Ask learners to predict the resulting error, then verify it on synthetic data. The lesson is to keep each kind of evidence in its proper layer.
Frequently asked questions
Can I translate the value school in amenity=school? Not in the technical tag used for category classification; translate its display label. Can I translate a local place name? Add or use a verified language-appropriate name under community practice, but do not invent or overwrite the established name casually. Are PBF identifiers safe as floating-point numbers? Large IDs can lose precision; use exact integer handling.
Does a PBF file contain images of maps? No, it normally contains encoded geographic objects and tags that mapping software can render. Is a relation a database relationship in the casual sense? It is a defined OSM object with members and roles. Does a successful parse prove route connectivity? No; test the reconstructed graph and its restrictions.
Sources and specification references
OpenStreetMap Wiki PBF file format and Protocol Buffer definitions: https://wiki.openstreetmap.org/wiki/PBF
OpenStreetMap tagging conventions: https://wiki.openstreetmap.org/wiki/Map_features
OpenStreetMap Foundation legal and licensing information: https://osmfoundation.org/wiki/Licence