translating docs

b103c196534e012c063817f73381ef260e1a5f29

README.md

@@ -1,7 +1,7 @@
 # alien
 
-Библиотека для типобезопасной работы с прямым доступом к памяти через
-примитивы Foreign Function & Memory API из JDK 22.
+Alien is a library for type safe direct memory access using structures introduced in
+JDK 22 [Foreign Function & Memory API](https://openjdk.org/jeps/454).
 
 ```scala
 Region.fresh.shared { implicit region =>
@@ -15,22 +15,22 @@ Region.fresh.shared { implicit region =>
 
 ```
 
-# Начало работы
+# Getting started
 
-Для использования библиотеки, добавьте следующую зависимость в файл `build.sbt` вашего проекта:
+Add alien as a dependency to your `build.sbt`:
 
 ```scala
 libraryDependencies += "com.yandex.classifieds" %% "alien-memory" % "0.1.0"
 ```
-### Поддерживаемые версии
+### Compatibility
 
-Библиотека доступна для использования в следующих версиях:
+Alien can be used with
 
 - Scala 2.13
-- Java 21 и Java 22
+- Java 21 or Java 22
 
-На момент выпуска Java 21, [Foreign Function & Memory API](https://openjdk.org/jeps/442) находилось в стадии превью, поэтому рекомендуется использовать предпочтительную версию Java 22.
+At the time of the release of Java 21, the Foreign Function & Memory API was in the preview stage, so it is recommended to use Java 22 with a final version of FFM.
 
-# Документация
+# Docs
 
-Документацию можно найти [здесь](https://yandexclassifieds.github.io/alien-memory/).
+More detailed docs can be found [here](https://yandexclassifieds.github.io/alien-memory/).

docs/index.yaml

@@ -1,18 +1,18 @@
 title: Alien Memory
-description: Библиотека для типобезопасной работы с прямым доступом к памяти через примитивы Foreign Function & Memory API из JDK 22.
+description: Alien is a library for type safe direct memory access using Foreign Function & Memory API from JDK 22.
 meta:
   title: Index
   noIndex: true
 links:
-  - title: Начало работы
-    description: Добавьте библиотеку в зависимости.
+  - title: Getting started
+    description: Dependencies and compatibility
     href: pages/getting_started.md
   - title: Memory
-    description: Аллокации памяти на хипе и вне его.
+    description: Heap and off-heap allocations
     href: pages/memory.md
   - title: Layouts
-    description: Описание разметки памяти.
+    description: Memory layouts
     href: pages/layouts.md
   - title: Regions
-    description: Менеджмент памяти.
+    description: Memory management
     href: pages/regions.md

docs/pages/getting_started.md

@@ -1,17 +1,15 @@
-# Начало работы
+# Getting started
 
-### Добавление в зависимости
-
-Для использования библиотеки, добавьте следующую зависимость в файл `build.sbt` вашего проекта:
+Add alien as a dependency to project's `build.sbt`:
 
 ```scala
 libraryDependencies += "com.yandex.classifieds" %% "alien-memory" % "0.1.0"
 ```
-### Поддерживаемые версии
+### Compatibility
 
-Библиотека доступна для использования в следующих версиях:
+Alien can be used with
 
 - Scala 2.13
-- Java 21 и Java 22
+- Java 21 or Java 22
 
-На момент выпуска Java 21, [Foreign Function & Memory API](https://openjdk.org/jeps/442) находилось в стадии превью, поэтому рекомендуется использовать предпочтительную версию Java 22.
+Java 21 release contains preview version of [Foreign Function & Memory API](https://openjdk.org/jeps/442) thus using Java 22 with final version of FFM is recommended.

docs/pages/layouts.md

@@ -1,62 +1,61 @@
 # Layout
 
-Layout - описание схемы данных, хранящихся в памяти. В основе лежит `java.lang.foreign.MemoryLayout`.
+Layout is a description of data structures stored in foreign memory. It is based on `java.lang.foreign.MemoryLayout`.
 
-Схема собирается из кирпичиков:
+Layout has the following building blocks:
 
-- `Value` - элементарный слой для целых чисел, символов и т.д.
+- `Value` - a basic layer for primitive types: numbers, characters, etc
   ```scala
-  val a = Values.Long //  слой под Long значения
+  val a = Values.Long //  layer for Long type values
   ```
-- `BoundedSequence` - контейнер для последовательности данных одного типа.
-  Упрощенно можно собирать последовательности с помощью оператора *, это повышает читабельность для матриц.
+- `BoundedSequence` - container for sequences of same-type data.
+  Sequences can be built using `*`, which makes matrix data definitions more readable
   ```scala
-  val a = Values.Long * 2 * 5 // матрица с 5 строчками и 2 столбцами
+  val a = Values.Long * 2 * 5 // matrix with 5 rows * 2 columns
   ```
-- `Aligned` - контейнер группы данных, который задает выравнивание в байтах для нижележащих данных.
+- `Aligned` - container for data sequence that specifies byte alignment for the underlying data.
   ```scala
-  val aligned = (Values.Long * 2 * 5).align[`2^8`] //  обеспечивает выделение памяти по адресу, кратному 256.
+  val aligned = (Values.Long * 2 * 5).align[`2^8`] //  allocated memory address is a multiple of 256.
   ```
-- `Padding` - "Пробел" в памяти, который не хранит данные, но добавляет смещение в байтах перед следующим элементом.
+- `Padding` - A "gap" in memory that doesn't store any meaningful data, but adds a byte offset before the next element.
 
   ```scala
-  val onlyPadding = Padding(32) // 32 пустых байта
+  val onlyPadding = Padding(32) // 32 empty bytes
   ```
-- `Dynamic` - контейнер группы данных. Выделяются два типа: структуры и объединения.
-
-  [Структуры](https://ru.wikipedia.org/wiki/Структура_(язык_Си)) записывают в память данные своих полей последовательно(
-  то же самое что и struct из C).
+- `Dynamic` - container for a group of data. There are 2 types: structures and unions.
 
-  [Объединения](https://ru.wikipedia.org/wiki/Объединение_(структура_данных)) же могут содержать что-то одно из 2 (то же
-  самое что и union из C)
+  [Structures](https://en.wikipedia.org/wiki/Struct_(C_programming_language)) has data of their fields written sequentially
+  (same as struct in C).
 
-  В alien для конструирования dynamic layout используются операторы:
+  [Unions](https://en.wikipedia.org/wiki/Union_type), on the other hand,  can contain one of two values (same as union from C)
+
+  alien has the following constructs to build dynamic layout:
 
   ```scala
-  <>: - дополнение текущего объединения другим объединением
+  <>: // adds this union to existing union
 
-  >> - инициализация слоя: переданный в такой конструктор name := layout теперь считается структурой или обьеденением из одного элемента
+  >> // initialize layer:  name := layout passed to this constructor is now a union with 1 element
 
-  >>: - дополнение текущей структуры другой структурой
+  >>: // add new structure to existing structure
   ```
 
-  Части структур и объединений нужно именовать с помощью оператора `:=`.
-  Пример:
+  Parts of unions and structures may be named using `:=`.
+
+  For example:
 
   ```scala
-  val a = "matrix" := Values.Long * 7 * 2 // матрица с именем matrix
-  val b = "array" := Values.Long * 5 // массив с именем array
-  val layout: ("matrix" := BoundedSequence[BoundedSequence[Value[Long]]]) >>: 
-              (>>["array" := BoundedSequence[Value[Long]]]) = a >>: b // структура из матрицы и массива
+  val a = "matrix" := Values.Long * 7 * 2 //  matrix named 'matrix'
+  val b = "array" := Values.Long * 5 // array named 'array'
+  val layout: ("matrix" := BoundedSequence[BoundedSequence[Value[Long]]]) >>:
+              (>>["array" := BoundedSequence[Value[Long]]]) = a >>: b // structure containing matrix and array
   ```
 
 ### Note
 
-При построении `Layout` нужно учитывать, что действует обратная (правая) ассоциативность. Например, при создании
-матрицы
+ When constructing `Layout` please, note, that it's dimensions have _reverse order_
+ compared to mathematics or programming languages
 
 ```scala
-val memL = "bitmap" := (Values.Long * height) * width
+val memL = "bitmap" := (Values.Long * columns) * rows // creates matrix rows*columns
 ```
 
-Сначала создается одна строка из height ячеек, затем эта строка масштабируется по ширине (width).

docs/pages/memory.md

@@ -1,22 +1,24 @@
 # Memory
 
-```Memory[L <: LayoutType, R <: Global]``` - обертка над ```java.lang.foreign.MemorySegment```. Позволяет выделять
-off-heap память для схем данных описанных через Layout. Первый параметр `L` - это тип layout для которого аллоцирована
-эта память. Второй параметр `R` - это тег региона внутри которого был аллоцирован этот сегмент памяти.
+```Memory[L <: LayoutType, R <: Global]``` is a wrapper over ```java.lang.foreign.MemorySegment```. Allows to allocate
+off-heap memory for data structures defined with [Layout](./layouts.md).
 
-Для доступа к сегменту памяти следует использовать `MemoryPtr*`
+`L` - layout type for which this memory is allocated.
+`R` -  region tag where this segment should be allocated
 
-## Аллокации
+To access memory segment use `MemoryPtr*`
 
-Все аллокации осуществляются с помощью ##malloc## установленного в системе.
-> По умолчанию все аллоцированные области заполняются нолями, чтобы этим пренебречь укажите ##JVM## флаг:
+## Allocations
+
+All allocations use system's ##malloc## .
+> By default, all allocated regions are initialized with 0s. To override this behaviour use ##JVM## parameter:
   ```-J-Djdk.internal.foreign.skipZeroMemory=true```
 
-Для аллокации сегментов есть следующие методы
+There are following methods for different allocations
 
 ### ##allocate##
 
-Использует методы аллокации региона лежащего в имплицитном контексте.
+Allocations use implicit region's properties
 
 ```scala
 implicit val region = Region.fresh.newShared()
@@ -27,7 +29,7 @@ region.close()
 
 ### ##allocateGC##
 
-Память проаллоцируется в offheap, но сборкой ее будет заниматься указанный сборщик мусора ##JVM##. Все такие сегменты памяти будут иметь тайп-тег ```Global```.
+Off-heap memory is allocated, but ##JVM## garbage collector will manage it. All such memory segments will have ```Global``` TypeTag.
 
 ```scala
 val layout = ("a" := Values.Int) >>: ("b" := Values.Int)
@@ -37,7 +39,7 @@ val memory = Memory.allocateGC(layout) // память лежит в offheap, н
 
 ### ##allocateStatic##
 
-Аллоцирует память, которая не удалится никогда и будет жить до окончания программы. Все такие сегменты памяти будут иметь тип-тег ```Global```.
+Allocated memory will never be collected and will be allocated as long as program runs. All such memory segments will have ```Global``` TypeTag.
 
 ```scala
 val layout = ("a" := Values.Int) >>: ("b" := Values.Int)
@@ -46,7 +48,7 @@ val memory = Memory.allocateStatic(layout)
 
 ### ##allocateManual##
 
-Аллоцирует память с помощью переданной ```java.lang.foreign.Arena```. Все такие сегменты памяти будут иметь тип-тег ```Global```.
+Allocates memory using the passed ```java.lang.foreign.Arena```. All such memory segments will have ```Global``` TypeTag.
 
 ```scala
 val layout = ("a" := Values.Int) >>: ("b" := Values.Int)
@@ -56,17 +58,18 @@ val memory = Memory.allocateManual(layout, Arena.ofAuto())
 
 ### ##allocateGlobal##
 
-Аллоцирует память с помощью региона с тегом ```Global``` взятым из имплицитного контекста. Все такие сегменты памяти будут иметь тип-тег ```Global```.
+Allocates memory using Region tagged ```Global``` from implicit context. All such memory segments will have ```Global``` TypeTag.
 
 ```scala
 val layout = ("a" := Values.Int) >>: ("b" := Values.Int)
 val memory = Memory.allocateGlobal(layout)
 ```
 
 
-## Байт-буферы
+## Byte buffers
 
-Каждый объект типа `Memory` можно преобразовывать в соответсвующий `ByteBuffer` и обратно. Обе структуры будут указывать на один и тот же сегмент памяти, вне зависимости от того где он лежит.
+Objects with type `Memory` can be transformed to and back from `ByteBuffer`. Both structures will point to the same
+memory segment regardless where it was located
 
 ```scala
 val heapMemory = Memory.ofArray(new Array[Byte](128))