storage
=======

.. automodule:: translate.storage
   :show-inheritance:

Editing existing units
----------------------

Use a unit's ``source`` property to change its source text, ``setcontext()`` to
change a supported context, and ``setid()`` to change an independent key. These
operations update the existing unit instead of replacing it, retaining its
translations and other metadata. They do not automatically mark translations
as needing review.

Key and context support depends on the format. The base ``setid()`` does
nothing, and an in-memory context is not necessarily serialized. Applications
must check format support and validate destination keys before editing. Some
formats expose composite identifiers, such as XLIFF file or segment identifiers;
these must be handled according to that format's setter conventions.

Source, key, and context setters invalidate attached store indexes. Use
``findid()``, ``findunit()``, or ``findunits()`` for subsequent lookups; they
rebuild the indexes when needed. Call ``makeindex()`` before accessing index
dictionaries directly after an edit. Add units through ``addunit()`` so their
setters can notify the store.

JSON supports changing nested key paths. YAML and TOML retain their original
documents to preserve formatting and comments; attached units support renaming
a key within its existing mapping, including nested mappings. Moving a stored
unit between mappings or renaming an array index raises ``ValueError``, as does
renaming to an existing key in the retained document.

XML source edits preserve language and text-node attributes and surrounding
metadata. Assigning the existing source text preserves inline markup; changing
the text replaces its inline content. Use the rich-source interface when the
replacement needs inline markup.


base
----

.. automodule:: translate.storage.base
   :members:
   :inherited-members:



catkeys
-------

.. automodule:: translate.storage.catkeys
   :members:
   :inherited-members:


cpo
---

.. automodule:: translate.storage.cpo
   :members:
   :inherited-members:


csvl10n
-------

.. automodule:: translate.storage.csvl10n
   :members:
   :inherited-members:


dtd
---

.. automodule:: translate.storage.dtd
   :members:
   :inherited-members:


_factory_classes
----------------

.. automodule:: translate.storage._factory_classes
   :members:
   :inherited-members:


factory
-------

.. automodule:: translate.storage.factory
   :members:
   :inherited-members:


fpo
---

.. automodule:: translate.storage.fpo
   :members:
   :inherited-members:


html
----

.. automodule:: translate.storage.html
   :members:
   :inherited-members:


ical
----

.. automodule:: translate.storage.ical
   :members:
   :inherited-members:


ini
---

.. automodule:: translate.storage.ini
   :members:
   :inherited-members:


jsonl10n
--------

.. automodule:: translate.storage.jsonl10n
   :members:
   :inherited-members:


lisa
----

.. automodule:: translate.storage.lisa
   :members:
   :inherited-members:


markdown
--------

.. automodule:: translate.storage.markdown
   :members:
   :inherited-members:


mo
--

.. automodule:: translate.storage.mo
   :members:
   :inherited-members:


mozilla_lang
------------

.. automodule:: translate.storage.mozilla_lang
   :members:
   :inherited-members:


odf_io
------

.. automodule:: translate.storage.odf_io
   :members:
   :inherited-members:


odf_shared
----------

.. automodule:: translate.storage.odf_shared
   :members:
   :inherited-members:


omegat
------

.. automodule:: translate.storage.omegat
   :members:
   :inherited-members:


oo
--

.. automodule:: translate.storage.oo
   :members:
   :inherited-members:


placeables
----------

.. automodule:: translate.storage.placeables
   :show-inheritance:


base
~~~~

.. automodule:: translate.storage.placeables.base
   :members:
   :inherited-members:


general
~~~~~~~

.. automodule:: translate.storage.placeables.general
   :members:
   :inherited-members:


interfaces
~~~~~~~~~~

.. automodule:: translate.storage.placeables.interfaces
   :members:
   :inherited-members:


lisa
~~~~

.. automodule:: translate.storage.placeables.lisa
   :members:
   :inherited-members:


parse
~~~~~

.. automodule:: translate.storage.placeables.parse
   :members:
   :inherited-members:


strelem
~~~~~~~

.. automodule:: translate.storage.placeables.strelem
   :members:
   :inherited-members:


terminology
~~~~~~~~~~~

.. automodule:: translate.storage.placeables.terminology
   :members:
   :inherited-members:


xliff
~~~~~

.. automodule:: translate.storage.placeables.xliff
   :members:
   :inherited-members:


php
---

.. automodule:: translate.storage.php
   :members:
   :inherited-members:


pocommon
--------

.. automodule:: translate.storage.pocommon
   :members:
   :inherited-members:


poheader
--------

.. automodule:: translate.storage.poheader
   :members:
   :inherited-members:


poparser
--------

.. automodule:: translate.storage.poparser
   :members:
   :inherited-members:


po
--

.. automodule:: translate.storage.po
   :members:
   :inherited-members:


poxliff
-------

.. automodule:: translate.storage.poxliff
   :members:
   :inherited-members:


properties
----------

.. automodule:: translate.storage.properties
   :members:
   :inherited-members:


pypo
----

.. automodule:: translate.storage.pypo
   :members:
   :inherited-members:


qm
--

.. automodule:: translate.storage.qm
   :members:
   :inherited-members:


qph
---

.. automodule:: translate.storage.qph
   :members:
   :inherited-members:


rc
--

.. automodule:: translate.storage.rc
   :members:
   :inherited-members:


statistics
----------

.. automodule:: translate.storage.statistics
   :members:
   :inherited-members:


subtitles
---------

.. automodule:: translate.storage.subtitles
   :members:
   :inherited-members:


symbian
-------

.. automodule:: translate.storage.symbian
   :members:
   :inherited-members:


tbx
---

.. automodule:: translate.storage.tbx
   :members:
   :inherited-members:


tiki
----

.. automodule:: translate.storage.tiki
   :members:
   :inherited-members:


tmx
---

.. automodule:: translate.storage.tmx
   :members:
   :inherited-members:


trados
------

.. automodule:: translate.storage.trados
   :members:
   :inherited-members:


ts2
---

.. automodule:: translate.storage.ts2
   :members:
   :inherited-members:


ts
--

.. automodule:: translate.storage.ts
   :members:
   :inherited-members:
   :deprecated:


txt
---

.. automodule:: translate.storage.txt
   :members:
   :inherited-members:


utx
---

.. automodule:: translate.storage.utx
   :members:
   :inherited-members:


wordfast
--------

.. automodule:: translate.storage.wordfast
   :members:
   :inherited-members:


workflow
--------

.. automodule:: translate.storage.workflow
   :members:
   :inherited-members:


xliff
-----

.. automodule:: translate.storage.xliff
   :members:
   :inherited-members:


xml_extract
-----------

.. automodule:: translate.storage.xml_extract
   :show-inheritance:


extract
~~~~~~~

.. automodule:: translate.storage.xml_extract.extract
   :members:
   :inherited-members:


generate
~~~~~~~~

.. automodule:: translate.storage.xml_extract.generate
   :members:
   :inherited-members:


misc
~~~~

.. automodule:: translate.storage.xml_extract.misc
   :members:
   :inherited-members:


unit_tree
~~~~~~~~~

.. automodule:: translate.storage.xml_extract.unit_tree
   :members:
   :inherited-members:


xpath_breadcrumb
~~~~~~~~~~~~~~~~

.. automodule:: translate.storage.xml_extract.xpath_breadcrumb
   :members:
   :inherited-members:


xml_name
--------

.. automodule:: translate.storage.xml_name
   :members:
   :inherited-members:
